2
0

basisu_transcoder.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352
  1. // basisu_transcoder.h
  2. // Copyright (C) 2019 Binomial LLC. All Rights Reserved.
  3. // Important: If compiling with gcc, be sure strict aliasing is disabled: -fno-strict-aliasing
  4. //
  5. // Licensed under the Apache License, Version 2.0 (the "License");
  6. // you may not use this file except in compliance with the License.
  7. // You may obtain a copy of the License at
  8. //
  9. // http://www.apache.org/licenses/LICENSE-2.0
  10. //
  11. // Unless required by applicable law or agreed to in writing, software
  12. // distributed under the License is distributed on an "AS IS" BASIS,
  13. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14. // See the License for the specific language governing permissions and
  15. // limitations under the License.
  16. #pragma once
  17. // Set BASISU_DEVEL_MESSAGES to 1 to enable debug printf()'s whenever an error occurs, for easier debugging during development.
  18. //#define BASISU_DEVEL_MESSAGES 1
  19. #include "basisu_transcoder_internal.h"
  20. #include "basisu_global_selector_palette.h"
  21. #include "basisu_file_headers.h"
  22. namespace basist
  23. {
  24. // High-level composite texture formats supported by the transcoder.
  25. // Each of these texture formats directly correspond to OpenGL/D3D/Vulkan etc. texture formats.
  26. // Notes:
  27. // - If you specify a texture format that supports alpha, but the .basis file doesn't have alpha, the transcoder will automatically output a
  28. // fully opaque (255) alpha channel.
  29. // - The PVRTC1 texture formats only support power of 2 dimension .basis files, but this may be relaxed in a future version.
  30. // - The PVRTC1 transcoders are real-time encoders, so don't expect the highest quality. We may add a slower encoder with improved quality.
  31. enum transcoder_texture_format
  32. {
  33. // Compressed formats
  34. // ETC1-2
  35. cTFETC1, // Opaque only, returns RGB or alpha data if cDecodeFlagsTranscodeAlphaDataToOpaqueFormats flag is specified
  36. cTFETC2, // Opaque+alpha, ETC2_EAC_A8 block followed by a ETC1 block, alpha channel will be opaque for opaque .basis files
  37. // BC1-5, BC7
  38. cTFBC1, // Opaque only, no punchthrough alpha support yet, transcodes alpha slice if cDecodeFlagsTranscodeAlphaDataToOpaqueFormats flag is specified
  39. cTFBC3, // Opaque+alpha, BC4 followed by a BC1 block, alpha channel will be opaque for opaque .basis files
  40. cTFBC4, // Red only, alpha slice is transcoded to output if cDecodeFlagsTranscodeAlphaDataToOpaqueFormats flag is specified
  41. cTFBC5, // XY: Two BC4 blocks, X=R and Y=Alpha, .basis file should have alpha data (if not Y will be all 255's)
  42. cTFBC7_M6_OPAQUE_ONLY, // Opaque only, RGB or alpha if cDecodeFlagsTranscodeAlphaDataToOpaqueFormats flag is specified. Highest quality of all the non-ETC1 formats.
  43. cTFBC7_M5, // Opaque+alpha, alpha channel will be opaque for opaque .basis files
  44. // PVRTC1 4bpp
  45. cTFPVRTC1_4_RGB, // Opaque only, RGB or alpha if cDecodeFlagsTranscodeAlphaDataToOpaqueFormats flag is specified, nearly lowest quality of any texture format.
  46. cTFPVRTC1_4_RGBA, // Opaque+alpha, most useful for simple opacity maps. If .basis file doens't have alpha cTFPVRTC1_4_RGB will be used instead. Lowest quality of any supported texture format.
  47. // ASTC
  48. cTFASTC_4x4, // Opaque+alpha, ASTC 4x4, alpha channel will be opaque for opaque .basis files. Transcoder uses RGB/RGBA/L/LA modes, void extent, and up to two ([0,47] and [0,255]) endpoint precisions.
  49. // ATC
  50. cTFATC_RGB, // Opaque, RGB or alpha if cDecodeFlagsTranscodeAlphaDataToOpaqueFormats flag is specified. ATI ATC (GL_ATC_RGB_AMD)
  51. cTFATC_RGBA_INTERPOLATED_ALPHA, // Opaque+alpha, alpha channel will be opaque for opaque .basis files. ATI ATC (ATC_RGBA_INTERPOLATED_ALPHA_AMD)
  52. cTFTotalBlockTextureFormats,
  53. // Uncompressed (raw pixel) formats
  54. cTFRGBA32 = cTFTotalBlockTextureFormats, // 32bpp RGBA image stored in raster (not block) order in memory, R is first byte, A is last byte.
  55. cTFRGB565, // 166pp RGB image stored in raster (not block) order in memory, R at bit position 11
  56. cTFBGR565, // 16bpp RGB image stored in raster (not block) order in memory, R at bit position 0
  57. cTFRGBA4444, // 16bpp RGBA image stored in raster (not block) order in memory, R at bit position 12, A at bit position 0
  58. cTFTotalTextureFormats
  59. };
  60. uint32_t basis_get_bytes_per_block(transcoder_texture_format fmt);
  61. const char* basis_get_format_name(transcoder_texture_format fmt);
  62. bool basis_transcoder_format_has_alpha(transcoder_texture_format fmt);
  63. basisu::texture_format basis_get_basisu_texture_format(transcoder_texture_format fmt);
  64. const char* basis_get_texture_type_name(basis_texture_type tex_type);
  65. bool basis_transcoder_format_is_uncompressed(transcoder_texture_format tex_type);
  66. bool basis_block_format_is_uncompressed(block_format tex_type);
  67. uint32_t basis_get_uncompressed_bytes_per_pixel(transcoder_texture_format fmt);
  68. class basisu_transcoder;
  69. // This struct holds all state used during transcoding. For video, it needs to persist between image transcodes (it holds the previous frame).
  70. // For threading you can use one state per thread.
  71. struct basisu_transcoder_state
  72. {
  73. struct block_preds
  74. {
  75. uint16_t m_endpoint_index;
  76. uint8_t m_pred_bits;
  77. };
  78. std::vector<block_preds> m_block_endpoint_preds[2];
  79. enum { cMaxPrevFrameLevels = 16 };
  80. std::vector<uint32_t> m_prev_frame_indices[2][cMaxPrevFrameLevels]; // [alpha_flag][level_index]
  81. };
  82. // Low-level helper class that does the actual transcoding.
  83. class basisu_lowlevel_transcoder
  84. {
  85. friend class basisu_transcoder;
  86. public:
  87. basisu_lowlevel_transcoder(const basist::etc1_global_selector_codebook *pGlobal_sel_codebook);
  88. bool decode_palettes(
  89. uint32_t num_endpoints, const uint8_t *pEndpoints_data, uint32_t endpoints_data_size,
  90. uint32_t num_selectors, const uint8_t *pSelectors_data, uint32_t selectors_data_size);
  91. bool decode_tables(const uint8_t *pTable_data, uint32_t table_data_size);
  92. bool transcode_slice(void *pDst_blocks, uint32_t num_blocks_x, uint32_t num_blocks_y, const uint8_t *pImage_data, uint32_t image_data_size, block_format fmt,
  93. uint32_t output_block_or_pixel_stride_in_bytes, bool wrap_addressing, bool bc1_allow_threecolor_blocks, const basis_file_header &header, const basis_slice_desc& slice_desc, uint32_t output_row_pitch_in_blocks_or_pixels = 0,
  94. basisu_transcoder_state *pState = nullptr, bool astc_transcode_alpha = false, void* pAlpha_blocks = nullptr, uint32_t output_rows_in_pixels = 0);
  95. private:
  96. typedef std::vector<endpoint> endpoint_vec;
  97. endpoint_vec m_endpoints;
  98. typedef std::vector<selector> selector_vec;
  99. selector_vec m_selectors;
  100. const etc1_global_selector_codebook *m_pGlobal_sel_codebook;
  101. huffman_decoding_table m_endpoint_pred_model, m_delta_endpoint_model, m_selector_model, m_selector_history_buf_rle_model;
  102. uint32_t m_selector_history_buf_size;
  103. basisu_transcoder_state m_def_state;
  104. };
  105. struct basisu_slice_info
  106. {
  107. uint32_t m_orig_width;
  108. uint32_t m_orig_height;
  109. uint32_t m_width;
  110. uint32_t m_height;
  111. uint32_t m_num_blocks_x;
  112. uint32_t m_num_blocks_y;
  113. uint32_t m_total_blocks;
  114. uint32_t m_compressed_size;
  115. uint32_t m_slice_index; // the slice index in the .basis file
  116. uint32_t m_image_index; // the source image index originally provided to the encoder
  117. uint32_t m_level_index; // the mipmap level within this image
  118. uint32_t m_unpacked_slice_crc16;
  119. bool m_alpha_flag; // true if the slice has alpha data
  120. bool m_iframe_flag; // true if the slice is an I-Frame
  121. };
  122. typedef std::vector<basisu_slice_info> basisu_slice_info_vec;
  123. struct basisu_image_info
  124. {
  125. uint32_t m_image_index;
  126. uint32_t m_total_levels;
  127. uint32_t m_orig_width;
  128. uint32_t m_orig_height;
  129. uint32_t m_width;
  130. uint32_t m_height;
  131. uint32_t m_num_blocks_x;
  132. uint32_t m_num_blocks_y;
  133. uint32_t m_total_blocks;
  134. uint32_t m_first_slice_index;
  135. bool m_alpha_flag; // true if the image has alpha data
  136. bool m_iframe_flag; // true if the image is an I-Frame
  137. };
  138. struct basisu_image_level_info
  139. {
  140. uint32_t m_image_index;
  141. uint32_t m_level_index;
  142. uint32_t m_orig_width;
  143. uint32_t m_orig_height;
  144. uint32_t m_width;
  145. uint32_t m_height;
  146. uint32_t m_num_blocks_x;
  147. uint32_t m_num_blocks_y;
  148. uint32_t m_total_blocks;
  149. uint32_t m_first_slice_index;
  150. bool m_alpha_flag; // true if the image has alpha data
  151. bool m_iframe_flag; // true if the image is an I-Frame
  152. };
  153. struct basisu_file_info
  154. {
  155. uint32_t m_version;
  156. uint32_t m_total_header_size;
  157. uint32_t m_total_selectors;
  158. uint32_t m_selector_codebook_size;
  159. uint32_t m_total_endpoints;
  160. uint32_t m_endpoint_codebook_size;
  161. uint32_t m_tables_size;
  162. uint32_t m_slices_size;
  163. basis_texture_type m_tex_type;
  164. uint32_t m_us_per_frame;
  165. // Low-level slice information (1 slice per image for color-only basis files, 2 for alpha basis files)
  166. basisu_slice_info_vec m_slice_info;
  167. uint32_t m_total_images; // total # of images
  168. std::vector<uint32_t> m_image_mipmap_levels; // the # of mipmap levels for each image
  169. uint32_t m_userdata0;
  170. uint32_t m_userdata1;
  171. bool m_etc1s; // always true for basis universal
  172. bool m_y_flipped; // true if the image was Y flipped
  173. bool m_has_alpha_slices; // true if the texture has alpha slices (even slices RGB, odd slices alpha)
  174. };
  175. // High-level transcoder class which accepts .basis file data and allows the caller to query information about the file and transcode image levels to various texture formats.
  176. // If you're just starting out this is the class you care about.
  177. class basisu_transcoder
  178. {
  179. basisu_transcoder(basisu_transcoder&);
  180. basisu_transcoder& operator= (const basisu_transcoder&);
  181. public:
  182. basisu_transcoder(const etc1_global_selector_codebook *pGlobal_sel_codebook);
  183. // Validates the .basis file. This computes a crc16 over the entire file, so it's slow.
  184. bool validate_file_checksums(const void *pData, uint32_t data_size, bool full_validation) const;
  185. // Quick header validation - no crc16 checks.
  186. bool validate_header(const void *pData, uint32_t data_size) const;
  187. basis_texture_type get_texture_type(const void *pData, uint32_t data_size) const;
  188. bool get_userdata(const void *pData, uint32_t data_size, uint32_t &userdata0, uint32_t &userdata1) const;
  189. // Returns the total number of images in the basis file (always 1 or more).
  190. // Note that the number of mipmap levels for each image may differ, and that images may have different resolutions.
  191. uint32_t get_total_images(const void *pData, uint32_t data_size) const;
  192. // Returns the number of mipmap levels in an image.
  193. uint32_t get_total_image_levels(const void *pData, uint32_t data_size, uint32_t image_index) const;
  194. // Returns basic information about an image. Note that orig_width/orig_height may not be a multiple of 4.
  195. bool get_image_level_desc(const void *pData, uint32_t data_size, uint32_t image_index, uint32_t level_index, uint32_t &orig_width, uint32_t &orig_height, uint32_t &total_blocks) const;
  196. // Returns information about the specified image.
  197. bool get_image_info(const void *pData, uint32_t data_size, basisu_image_info &image_info, uint32_t image_index) const;
  198. // Returns information about the specified image's mipmap level.
  199. bool get_image_level_info(const void *pData, uint32_t data_size, basisu_image_level_info &level_info, uint32_t image_index, uint32_t level_index) const;
  200. // Get a description of the basis file and low-level information about each slice.
  201. bool get_file_info(const void *pData, uint32_t data_size, basisu_file_info &file_info) const;
  202. // start_transcoding() must be called before calling transcode_slice() or transcode_image_level().
  203. // This decompresses the selector/endpoint codebooks, so ideally you would only call this once per .basis file (not each image/mipmap level).
  204. bool start_transcoding(const void *pData, uint32_t data_size) const;
  205. // Returns true if start_transcoding() has been called.
  206. bool get_ready_to_transcode() const { return m_lowlevel_decoder.m_endpoints.size() > 0; }
  207. enum
  208. {
  209. // PVRTC1: texture will use wrap addressing vs. clamp (most PVRTC viewer tools assume wrap addressing, so we default to wrap although that can cause edge artifacts)
  210. cDecodeFlagsPVRTCWrapAddressing = 1,
  211. // PVRTC1: decode non-pow2 ETC1S texture level to the next larger power of 2 (not implemented yet, but we're going to support it). Ignored if the slice's dimensions are already a power of 2.
  212. cDecodeFlagsPVRTCDecodeToNextPow2 = 2,
  213. // When decoding to an opaque texture format, if the basis file has alpha, decode the alpha slice instead of the color slice to the output texture format.
  214. // This is primarily to allow decoding of textures with alpha to multiple ETC1 textures (one for color, another for alpha).
  215. cDecodeFlagsTranscodeAlphaDataToOpaqueFormats = 4,
  216. // Forbid usage of BC1 3 color blocks (we don't support BC1 punchthrough alpha yet).
  217. // This flag is used internally when decoding to BC3.
  218. cDecodeFlagsBC1ForbidThreeColorBlocks = 8,
  219. // The output buffer contains alpha endpoint/selector indices.
  220. // Used internally when decoding formats like ASTC that require both color and alpha data to be available when transcoding to the output format.
  221. cDecodeFlagsOutputHasAlphaIndices = 16,
  222. };
  223. // transcode_image_level() decodes a single mipmap level from the .basis file to any of the supported output texture formats.
  224. // It'll first find the slice(s) to transcode, then call transcode_slice() one or two times to decode both the color and alpha texture data (or RG texture data from two slices for BC5).
  225. // If the .basis file doesn't have alpha slices, the output alpha blocks will be set to fully opaque (all 255's).
  226. // Currently, to decode to PVRTC1 the basis texture's dimensions in pixels must be a power of 2, due to PVRTC1 format requirements.
  227. // output_blocks_buf_size_in_blocks_or_pixels should be at least the image level's total_blocks (num_blocks_x * num_blocks_y), or the total number of output pixels if fmt==cTFRGBA32.
  228. // output_row_pitch_in_blocks_or_pixels: Number of blocks or pixels per row. If 0, the transcoder uses the slice's num_blocks_x or orig_width (NOT num_blocks_x * 4). Ignored for PVRTC1 (due to texture swizzling).
  229. // output_rows_in_pixels: Ignored unless fmt is cRGBA32. The total number of output rows in the output buffer. If 0, the transcoder assumes the slice's orig_height (NOT num_blocks_y * 4).
  230. // Notes:
  231. // - basisu_transcoder_init() must have been called first to initialize the transcoder lookup tables before calling this function.
  232. // - This method assumes the output texture buffer is readable. In some cases to handle alpha, the transcoder will write temporary data to the output texture in
  233. // a first pass, which will be read in a second pass.
  234. bool transcode_image_level(
  235. const void *pData, uint32_t data_size,
  236. uint32_t image_index, uint32_t level_index,
  237. void *pOutput_blocks, uint32_t output_blocks_buf_size_in_blocks_or_pixels,
  238. transcoder_texture_format fmt,
  239. uint32_t decode_flags = cDecodeFlagsPVRTCWrapAddressing, uint32_t output_row_pitch_in_blocks_or_pixels = 0, basisu_transcoder_state *pState = nullptr, uint32_t output_rows_in_pixels = 0) const;
  240. // Finds the basis slice corresponding to the specified image/level/alpha params, or -1 if the slice can't be found.
  241. int find_slice(const void *pData, uint32_t data_size, uint32_t image_index, uint32_t level_index, bool alpha_data) const;
  242. // transcode_slice() decodes a single slice from the .basis file. It's a low-level API - most likely you want to use transcode_image_level().
  243. // This is a low-level API, and will be needed to be called multiple times to decode some texture formats (like BC3, BC5, or ETC2).
  244. // output_blocks_buf_size_in_blocks_or_pixels is just used for verification to make sure the output buffer is large enough.
  245. // output_blocks_buf_size_in_blocks_or_pixels should be at least the image level's total_blocks (num_blocks_x * num_blocks_y), or the total number of output pixels if fmt==cTFRGBA32.
  246. // output_block_stride_in_bytes: Number of bytes between each output block.
  247. // output_row_pitch_in_blocks_or_pixels: Number of blocks or pixels per row. If 0, the transcoder uses the slice's num_blocks_x or orig_width (NOT num_blocks_x * 4). Ignored for PVRTC1 (due to texture swizzling).
  248. // output_rows_in_pixels: Ignored unless fmt is cRGBA32. The total number of output rows in the output buffer. If 0, the transcoder assumes the slice's orig_height (NOT num_blocks_y * 4).
  249. // Notes:
  250. // - basisu_transcoder_init() must have been called first to initialize the transcoder lookup tables before calling this function.
  251. bool transcode_slice(const void *pData, uint32_t data_size, uint32_t slice_index,
  252. void *pOutput_blocks, uint32_t output_blocks_buf_size_in_blocks_or_pixels,
  253. block_format fmt, uint32_t output_block_stride_in_bytes, uint32_t decode_flags = cDecodeFlagsPVRTCWrapAddressing, uint32_t output_row_pitch_in_blocks_or_pixels = 0, basisu_transcoder_state * pState = nullptr, void* pAlpha_blocks = nullptr, uint32_t output_rows_in_pixels = 0) const;
  254. private:
  255. mutable basisu_lowlevel_transcoder m_lowlevel_decoder;
  256. int find_first_slice_index(const void* pData, uint32_t data_size, uint32_t image_index, uint32_t level_index) const;
  257. bool validate_header_quick(const void* pData, uint32_t data_size) const;
  258. };
  259. // basisu_transcoder_init() must be called before a .basis file can be transcoded.
  260. void basisu_transcoder_init();
  261. enum debug_flags_t
  262. {
  263. cDebugFlagVisCRs = 1,
  264. cDebugFlagVisBC1Sels = 2,
  265. cDebugFlagVisBC1Endpoints = 4
  266. };
  267. uint32_t get_debug_flags();
  268. void set_debug_flags(uint32_t f);
  269. } // namespace basisu