// example_transcoding.cpp: Very simple transcoding-only example. Does not depend on the basisu encoder library at all, just basisu_transcoder.cpp. // You can use AMD Compressonator or Microsoft's DirectXTex tools on github to view the written DX10 .DDS file. // // Two demos run in main(): // 1. KTX2 -> BC7 -> writes out.dds (uses basist::ktx2_transcoder). // 2. .DDS (BC1 and BC7, mipmapped) -> RGBA -> writes a .BMP per mip (uses basist::dds_transcoder). See transcode_dds_to_bmps() below. #include #include // for testing //#define BASISD_SUPPORT_XUASTC (0) //#define BASISD_SUPPORT_KTX2_ZSTD (0) #include "../transcoder/basisu_transcoder.h" #include "utils.h" #include // ============================================================================================================ // DDS transcoding example. // // Loads a Microsoft .DDS file with basist::dds_transcoder, prints its per-mip info, transcodes EVERY mipmap // level to 32-bpp RGBA, and writes each decoded mip out as an uncompressed .BMP. // // The dds_transcoder API deliberately mirrors ktx2_transcoder, so the usage pattern is the same: // init() -> start_transcoding() -> get_*() / get_image_level_info() -> transcode_image_level() // // pName is a bare filename looked up in ../test_files first (when run from the build dir), then the cwd. // pOutput_prefix is prepended to each written "_layer_face_mip.bmp". // ============================================================================================================ static bool transcode_dds_to_bmps(const char* pName, const char* pOutput_prefix) { // 1. Read the entire .DDS file into memory. dds_transcoder BORROWS this buffer (it does not copy it), so // the data must remain alive for as long as we call transcode methods on the transcoder. utils::uint8_vec dds_file_data; const std::string test_files_path = std::string("../test_files/") + pName; if (!utils::read_file(test_files_path.c_str(), dds_file_data)) { if (!utils::read_file(pName, dds_file_data)) { fprintf(stderr, "Can't read DDS file %s or %s\n", test_files_path.c_str(), pName); return false; } } if (dds_file_data.size() > UINT32_MAX) { fprintf(stderr, "DDS file too large\n"); return false; } // 2. init() parses the DDS header(s), detects and validates the format/layout, and precomputes the byte // range of every (layer, face, level) slice. It returns false on any malformed or unsupported input // (the parser is hardened against corrupt/truncated files). basist::dds_transcoder dds; if (!dds.init(dds_file_data.data(), (uint32_t)dds_file_data.size())) { fprintf(stderr, "dds_transcoder::init() failed on %s (unsupported or corrupt DDS)\n", pName); return false; } // 3. start_transcoding() must be called before transcoding. For DDS there are no global tables to unpack // (unlike ETC1S KTX2), so this just verifies init() succeeded -- it exists to mirror ktx2_transcoder. if (!dds.start_transcoding()) { fprintf(stderr, "dds_transcoder::start_transcoding() failed\n"); return false; } // Geometry accessors (valid after init), mirroring ktx2_transcoder. get_layers() returns 0 when the file // is not a texture array (the KTX2 convention), so treat 0 as a single layer when iterating. const uint32_t num_levels = dds.get_levels(); const uint32_t num_layers = dds.get_layers(); const uint32_t eff_layers = num_layers ? num_layers : 1; const uint32_t num_faces = dds.get_faces(); const bool has_alpha = (dds.get_has_alpha() != 0); printf("\nLoaded %s\n", pName); printf(" %ux%u, mip levels: %u, array layers: %u, faces: %u, has_alpha: %u, sRGB: %u\n", dds.get_width(), dds.get_height(), num_levels, num_layers, num_faces, dds.get_has_alpha(), dds.is_srgb() ? 1 : 0); // get_format() returns the closest transcoder_texture_format the file's contents map to (i.e. what a // passthrough transcode would emit). basis_get_format_name() turns it into a printable string. printf(" contained format: %s\n", basist::basis_get_format_name(dds.get_format())); // 4. Walk every image (array layer, cubemap face, mip level), print its info, transcode it to RGBA, and // write a .BMP. Most 2D textures have eff_layers==1 and num_faces==1, so this is usually just the mips. for (uint32_t layer = 0; layer < eff_layers; layer++) { for (uint32_t face = 0; face < num_faces; face++) { for (uint32_t level = 0; level < num_levels; level++) { // Per-image info (the same struct ktx2_transcoder uses). m_orig_width/height are the real pixel // dimensions (may not be a multiple of the 4x4 block size); m_width/height are padded up to it. basist::ktx2_image_level_info level_info; if (!dds.get_image_level_info(level_info, level, layer, face)) { fprintf(stderr, "get_image_level_info() failed (level %u, layer %u, face %u)\n", level, layer, face); return false; } printf(" mip %2u: %ux%u (%u blocks, %ux%u), alpha: %u\n", level, level_info.m_orig_width, level_info.m_orig_height, level_info.m_total_blocks, level_info.m_num_blocks_x, level_info.m_num_blocks_y, level_info.m_alpha_flag); // Transcode this mip to 32-bpp RGBA. cTFRGBA32 is an UNCOMPRESSED target, so the output buffer // holds one 32-bit pixel per texel (not 4x4 blocks), tightly packed at the image's actual // dimensions. image_u8's pixels are color_quad_u8 {r,g,b,a}, which is exactly the RGBA32 byte // layout, so we can transcode straight into the image's pixel buffer. utils::image_u8 img(level_info.m_orig_width, level_info.m_orig_height); const uint32_t num_output_pixels = level_info.m_orig_width * level_info.m_orig_height; // For uncompressed targets the "output_blocks_buf_size_in_blocks_or_pixels" argument is a PIXEL // count; the transcoder uses it to verify the destination buffer is large enough. if (!dds.transcode_image_level(level, layer, face, img.get_pixels().data(), num_output_pixels, basist::transcoder_texture_format::cTFRGBA32)) { fprintf(stderr, "transcode_image_level() to RGBA32 failed (level %u, layer %u, face %u)\n", level, layer, face); return false; } // Save the decoded image. 32-bpp BGRA when the source has alpha (e.g. BC7), else 24-bpp BGR. char out_filename[300]; snprintf(out_filename, sizeof(out_filename), "%s_layer%u_face%u_mip%02u.bmp", pOutput_prefix, layer, face, level); if (!utils::save_bmp(out_filename, img, has_alpha)) { fprintf(stderr, "save_bmp(%s) failed\n", out_filename); return false; } printf(" wrote %s\n", out_filename); } } } return true; } int main() { basist::basisu_transcoder_init(); // Read the .KTX2 file's data into memory. utils::uint8_vec ktx2_file_data; if (!utils::read_file("../test_files/base_xuastc_arith.ktx2", ktx2_file_data)) { if (!utils::read_file("base_xuastc_arith.ktx2", ktx2_file_data)) { fprintf(stderr, "Can't read file ../test_files/base_xuastc_arith.ktx2 or base_xuastc_arith.ktx2\n"); return EXIT_FAILURE; } } printf("Read file base_xuastc_arith.ktx2\n"); if (ktx2_file_data.size() > UINT32_MAX) { fprintf(stderr, "KTX2 file too large\n"); return EXIT_FAILURE; } basist::ktx2_transcoder transcoder; // Initialize the transcoder. if (!transcoder.init(ktx2_file_data.data(), (uint32_t)ktx2_file_data.size())) return EXIT_FAILURE; const uint32_t width = transcoder.get_width(); const uint32_t height = transcoder.get_height(); const uint32_t num_levels = transcoder.get_levels(); const bool is_srgb = transcoder.is_srgb(); printf("KTX2 dimensions: %ux%u, num mip levels: %u, sRGB: %u\n", width, height, num_levels, is_srgb); // Can't transcode HDR to LDR formats. if (transcoder.is_hdr()) { fprintf(stderr, "Expected LDR KTX2 file\n"); return EXIT_FAILURE; } // Ensure BC7 support was enabled at compilation time (it will be enabled by default). const basist::transcoder_texture_format tex_fmt = basist::transcoder_texture_format::cTFBC7_RGBA; if (!basist::basis_is_format_supported(tex_fmt, transcoder.get_basis_tex_format())) { printf("BC7 was disabled in the transcoder at compilation\n"); return EXIT_FAILURE; } // Begin transcoding (this will be a no-op with UASTC HDR textures, but you still need to do it. For ETC1S it'll unpack the global codebooks). transcoder.start_transcoding(); // Transcode to BC7 and write a BC7 .DDS file. // Bytes per block (8 or 16 for BC1-7) const uint32_t bytes_per_block = basist::basis_get_bytes_per_block_or_pixel(tex_fmt); // Compute total bytes needed to transcode the slice const uint32_t total_bytes = basist::basis_compute_transcoded_image_size_in_bytes(tex_fmt, width, height); // Derive the total number of blocks the output buffer can hold. The transcoder will use this to verify the buffer is large enough. const uint32_t total_blocks = total_bytes / bytes_per_block; // Allocate the buffer to hold the blocks utils::uint8_vec tex_buffer(total_bytes); // Transcode the level bool status = transcoder.transcode_image_level(0, 0, 0, tex_buffer.data(), total_blocks, tex_fmt, 0); if (!status) { fprintf(stderr, "transcoder.transcode_image_level() failed\n"); return EXIT_FAILURE; } // Write an sRGB DX10-style .DDS file. if (!utils::save_dds("out.dds", width, height, tex_buffer.data(), 8, DXGI_FORMAT_BC7_UNORM_SRGB, true, true)) { fprintf(stderr, "save_dds() failed\n"); return EXIT_FAILURE; } printf("Wrote out.dds\n"); // --- DDS transcoding example ----------------------------------------------------------------------------- // Load two example .DDS files made with texconv -- a BC1/DXT1 color texture (kodim01, no alpha) and a BC7 // texture with alpha (texarray_alpha_0) -- and transcode every mip level of each to RGBA, writing .BMPs. if (!transcode_dds_to_bmps("kodim01.dds", "kodim01_bc1")) return EXIT_FAILURE; if (!transcode_dds_to_bmps("texarray_alpha_0.dds", "texarray_alpha_0_bc7")) return EXIT_FAILURE; return EXIT_SUCCESS; }