image: add crn support to the image plugin.
[xonotic/netradiant.git] / libs / crunch / crnlib.h
1 // File: crnlib.h - Advanced DXTn texture compression library.
2 // Copyright (c) 2010-2016 Richard Geldreich, Jr. and Binomial LLC
3 // See copyright notice and license at the end of this file.
4 //
5 // This header file contains the public crnlib declarations for DXTn,
6 // clustered DXTn, and CRN compression/decompression.
7 //
8 // Note: This library does NOT need to be linked into your game executable if
9 // all you want to do is transcode .CRN files to raw DXTn bits at run-time.
10 // The crn_decomp.h header file library contains all the code necessary for
11 // decompression.
12 //
13 // Important: If compiling with gcc, be sure strict aliasing is disabled: -fno-strict-aliasing
14 #ifndef CRNLIB_H
15 #define CRNLIB_H
16
17 #ifdef _MSC_VER
18 #pragma warning(disable : 4127)  //  conditional expression is constant
19 #endif
20
21 #define CRNLIB_VERSION 104
22
23 #define CRNLIB_SUPPORT_ATI_COMPRESS 0
24 #define CRNLIB_SUPPORT_SQUISH 0
25
26 typedef unsigned char crn_uint8;
27 typedef unsigned short crn_uint16;
28 typedef unsigned int crn_uint32;
29 typedef signed char crn_int8;
30 typedef signed short crn_int16;
31 typedef signed int crn_int32;
32 typedef unsigned int crn_bool;
33
34 // crnlib can compress to these file types.
35 enum crn_file_type {
36   // .CRN
37   cCRNFileTypeCRN = 0,
38
39   // .DDS using regular DXT or clustered DXT
40   cCRNFileTypeDDS,
41
42   cCRNFileTypeForceDWORD = 0xFFFFFFFF
43 };
44
45 // Supported compressed pixel formats.
46 // Basically all the standard DX9 formats, with some swizzled DXT5 formats
47 // (most of them supported by ATI's Compressonator), along with some ATI/X360 GPU specific formats.
48 enum crn_format {
49   cCRNFmtInvalid = -1,
50
51   cCRNFmtDXT1 = 0,
52
53   cCRNFmtFirstValid = cCRNFmtDXT1,
54
55   // cCRNFmtDXT3 is not currently supported when writing to CRN - only DDS.
56   cCRNFmtDXT3,
57
58   cCRNFmtDXT5,
59
60   // Various DXT5 derivatives
61   cCRNFmtDXT5_CCxY,  // Luma-chroma
62   cCRNFmtDXT5_xGxR,  // Swizzled 2-component
63   cCRNFmtDXT5_xGBR,  // Swizzled 3-component
64   cCRNFmtDXT5_AGBR,  // Swizzled 4-component
65
66   // ATI 3DC and X360 DXN
67   cCRNFmtDXN_XY,
68   cCRNFmtDXN_YX,
69
70   // DXT5 alpha blocks only
71   cCRNFmtDXT5A,
72
73   cCRNFmtETC1,
74   cCRNFmtETC2,
75   cCRNFmtETC2A,
76
77   cCRNFmtTotal,
78
79   cCRNFmtForceDWORD = 0xFFFFFFFF
80 };
81
82 // Various library/file format limits.
83 enum crn_limits {
84   // Max. mipmap level resolution on any axis.
85   cCRNMaxLevelResolution = 4096,
86
87   cCRNMinPaletteSize = 8,
88   cCRNMaxPaletteSize = 8192,
89
90   cCRNMaxFaces = 6,
91   cCRNMaxLevels = 16,
92
93   cCRNMaxHelperThreads = 16,
94
95   cCRNMinQualityLevel = 0,
96   cCRNMaxQualityLevel = 255
97 };
98
99 // CRN/DDS compression flags.
100 // See the m_flags member in the crn_comp_params struct, below.
101 enum crn_comp_flags {
102   // Enables perceptual colorspace distance metrics if set.
103   // Important: Be sure to disable this when compressing non-sRGB colorspace images, like normal maps!
104   // Default: Set
105   cCRNCompFlagPerceptual = 1,
106
107   // Enables (up to) 8x8 macroblock usage if set. If disabled, only 4x4 blocks are allowed.
108   // Compression ratio will be lower when disabled, but may cut down on blocky artifacts because the process used to determine
109   // where large macroblocks can be used without artifacts isn't perfect.
110   // Default: Set.
111   cCRNCompFlagHierarchical = 2,
112
113   // cCRNCompFlagQuick disables several output file optimizations - intended for things like quicker previews.
114   // Default: Not set.
115   cCRNCompFlagQuick = 4,
116
117   // DXT1: OK to use DXT1 alpha blocks for better quality or DXT1A transparency.
118   // DXT5: OK to use both DXT5 block types.
119   // Currently only used when writing to .DDS files, as .CRN uses only a subset of the possible DXTn block types.
120   // Default: Set.
121   cCRNCompFlagUseBothBlockTypes = 8,
122
123   // OK to use DXT1A transparent indices to encode black (assumes pixel shader ignores fetched alpha).
124   // Currently only used when writing to .DDS files, .CRN never uses alpha blocks.
125   // Default: Not set.
126   cCRNCompFlagUseTransparentIndicesForBlack = 16,
127
128   // Disables endpoint caching, for more deterministic output.
129   // Currently only used when writing to .DDS files.
130   // Default: Not set.
131   cCRNCompFlagDisableEndpointCaching = 32,
132
133   // If enabled, use the cCRNColorEndpointPaletteSize, etc. params to control the CRN palette sizes. Only useful when writing to .CRN files.
134   // Default: Not set.
135   cCRNCompFlagManualPaletteSizes = 64,
136
137   // If enabled, DXT1A alpha blocks are used to encode single bit transparency.
138   // Default: Not set.
139   cCRNCompFlagDXT1AForTransparency = 128,
140
141   // If enabled, the DXT1 compressor's color distance metric assumes the pixel shader will be converting the fetched RGB results to luma (Y part of YCbCr).
142   // This increases quality when compressing grayscale images, because the compressor can spread the luma error amoung all three channels (i.e. it can generate blocks
143   // with some chroma present if doing so will ultimately lead to lower luma error).
144   // Only enable on grayscale source images.
145   // Default: Not set.
146   cCRNCompFlagGrayscaleSampling = 256,
147
148   // If enabled, debug information will be output during compression.
149   // Default: Not set.
150   cCRNCompFlagDebugging = 0x80000000,
151
152   cCRNCompFlagForceDWORD = 0xFFFFFFFF
153 };
154
155 // Controls DXTn quality vs. speed control - only used when compressing to .DDS.
156 enum crn_dxt_quality {
157   cCRNDXTQualitySuperFast,
158   cCRNDXTQualityFast,
159   cCRNDXTQualityNormal,
160   cCRNDXTQualityBetter,
161   cCRNDXTQualityUber,
162
163   cCRNDXTQualityTotal,
164
165   cCRNDXTQualityForceDWORD = 0xFFFFFFFF
166 };
167
168 // Which DXTn compressor to use when compressing to plain (non-clustered) .DDS.
169 enum crn_dxt_compressor_type {
170   cCRNDXTCompressorCRN,   // Use crnlib's ETC1 or DXTc block compressor (default, highest quality, comparable or better than ati_compress or squish, and crnlib's ETC1 is a lot fasterw with similiar quality to Erricson's)
171   cCRNDXTCompressorCRNF,  // Use crnlib's "fast" DXTc block compressor
172   cCRNDXTCompressorRYG,   // Use RYG's DXTc block compressor (low quality, but very fast)
173
174 #if CRNLIB_SUPPORT_ATI_COMPRESS
175   cCRNDXTCompressorATI,
176 #endif
177
178 #if CRNLIB_SUPPORT_SQUISH
179   cCRNDXTCompressorSquish,
180 #endif
181
182   cCRNTotalDXTCompressors,
183
184   cCRNDXTCompressorForceDWORD = 0xFFFFFFFF
185 };
186
187 // Progress callback function.
188 // Processing will stop prematurely (and fail) if the callback returns false.
189 // phase_index, total_phases - high level progress
190 // subphase_index, total_subphases - progress within current phase
191 typedef crn_bool (*crn_progress_callback_func)(crn_uint32 phase_index, crn_uint32 total_phases, crn_uint32 subphase_index, crn_uint32 total_subphases, void* pUser_data_ptr);
192
193 // CRN/DDS compression parameters struct.
194 struct crn_comp_params {
195   inline crn_comp_params() { clear(); }
196
197   // Clear struct to default parameters.
198   inline void clear() {
199     m_size_of_obj = sizeof(*this);
200     m_file_type = cCRNFileTypeCRN;
201     m_faces = 1;
202     m_width = 0;
203     m_height = 0;
204     m_levels = 1;
205     m_format = cCRNFmtDXT1;
206     m_flags = cCRNCompFlagPerceptual | cCRNCompFlagHierarchical | cCRNCompFlagUseBothBlockTypes;
207
208     for (crn_uint32 f = 0; f < cCRNMaxFaces; f++)
209       for (crn_uint32 l = 0; l < cCRNMaxLevels; l++)
210         m_pImages[f][l] = NULL;
211
212     m_target_bitrate = 0.0f;
213     m_quality_level = cCRNMaxQualityLevel;
214     m_dxt1a_alpha_threshold = 128;
215     m_dxt_quality = cCRNDXTQualityUber;
216     m_dxt_compressor_type = cCRNDXTCompressorCRN;
217     m_alpha_component = 3;
218
219     m_crn_adaptive_tile_color_psnr_derating = 2.0f;
220     m_crn_adaptive_tile_alpha_psnr_derating = 2.0f;
221     m_crn_color_endpoint_palette_size = 0;
222     m_crn_color_selector_palette_size = 0;
223     m_crn_alpha_endpoint_palette_size = 0;
224     m_crn_alpha_selector_palette_size = 0;
225
226     m_num_helper_threads = 0;
227     m_userdata0 = 0;
228     m_userdata1 = 0;
229     m_pProgress_func = NULL;
230     m_pProgress_func_data = NULL;
231   }
232
233   inline bool operator==(const crn_comp_params& rhs) const {
234 #define CRNLIB_COMP(x)  \
235   do {                  \
236     if ((x) != (rhs.x)) \
237       return false;     \
238   } while (0)
239     CRNLIB_COMP(m_size_of_obj);
240     CRNLIB_COMP(m_file_type);
241     CRNLIB_COMP(m_faces);
242     CRNLIB_COMP(m_width);
243     CRNLIB_COMP(m_height);
244     CRNLIB_COMP(m_levels);
245     CRNLIB_COMP(m_format);
246     CRNLIB_COMP(m_flags);
247     CRNLIB_COMP(m_target_bitrate);
248     CRNLIB_COMP(m_quality_level);
249     CRNLIB_COMP(m_dxt1a_alpha_threshold);
250     CRNLIB_COMP(m_dxt_quality);
251     CRNLIB_COMP(m_dxt_compressor_type);
252     CRNLIB_COMP(m_alpha_component);
253     CRNLIB_COMP(m_crn_adaptive_tile_color_psnr_derating);
254     CRNLIB_COMP(m_crn_adaptive_tile_alpha_psnr_derating);
255     CRNLIB_COMP(m_crn_color_endpoint_palette_size);
256     CRNLIB_COMP(m_crn_color_selector_palette_size);
257     CRNLIB_COMP(m_crn_alpha_endpoint_palette_size);
258     CRNLIB_COMP(m_crn_alpha_selector_palette_size);
259     CRNLIB_COMP(m_num_helper_threads);
260     CRNLIB_COMP(m_userdata0);
261     CRNLIB_COMP(m_userdata1);
262     CRNLIB_COMP(m_pProgress_func);
263     CRNLIB_COMP(m_pProgress_func_data);
264
265     for (crn_uint32 f = 0; f < cCRNMaxFaces; f++)
266       for (crn_uint32 l = 0; l < cCRNMaxLevels; l++)
267         CRNLIB_COMP(m_pImages[f][l]);
268
269 #undef CRNLIB_COMP
270     return true;
271   }
272
273   // Returns true if the input parameters are reasonable.
274   inline bool check() const {
275     if ((m_file_type > cCRNFileTypeDDS) ||
276         (((int)m_quality_level < (int)cCRNMinQualityLevel) || ((int)m_quality_level > (int)cCRNMaxQualityLevel)) ||
277         (m_dxt1a_alpha_threshold > 255) ||
278         ((m_faces != 1) && (m_faces != 6)) ||
279         ((m_width < 1) || (m_width > cCRNMaxLevelResolution)) ||
280         ((m_height < 1) || (m_height > cCRNMaxLevelResolution)) ||
281         ((m_levels < 1) || (m_levels > cCRNMaxLevels)) ||
282         ((m_format < cCRNFmtDXT1) || (m_format >= cCRNFmtTotal)) ||
283         ((m_crn_color_endpoint_palette_size) && ((m_crn_color_endpoint_palette_size < cCRNMinPaletteSize) || (m_crn_color_endpoint_palette_size > cCRNMaxPaletteSize))) ||
284         ((m_crn_color_selector_palette_size) && ((m_crn_color_selector_palette_size < cCRNMinPaletteSize) || (m_crn_color_selector_palette_size > cCRNMaxPaletteSize))) ||
285         ((m_crn_alpha_endpoint_palette_size) && ((m_crn_alpha_endpoint_palette_size < cCRNMinPaletteSize) || (m_crn_alpha_endpoint_palette_size > cCRNMaxPaletteSize))) ||
286         ((m_crn_alpha_selector_palette_size) && ((m_crn_alpha_selector_palette_size < cCRNMinPaletteSize) || (m_crn_alpha_selector_palette_size > cCRNMaxPaletteSize))) ||
287         (m_alpha_component > 3) ||
288         (m_num_helper_threads > cCRNMaxHelperThreads) ||
289         (m_dxt_quality > cCRNDXTQualityUber) ||
290         (m_dxt_compressor_type >= cCRNTotalDXTCompressors)) {
291       return false;
292     }
293     return true;
294   }
295
296   // Helper to set/get flags from m_flags member.
297   inline bool get_flag(crn_comp_flags flag) const { return (m_flags & flag) != 0; }
298   inline void set_flag(crn_comp_flags flag, bool val) {
299     m_flags &= ~flag;
300     if (val)
301       m_flags |= flag;
302   }
303
304   crn_uint32 m_size_of_obj;
305
306   crn_file_type m_file_type;  // Output file type: cCRNFileTypeCRN or cCRNFileTypeDDS.
307
308   crn_uint32 m_faces;   // 1 (2D map) or 6 (cubemap)
309   crn_uint32 m_width;   // [1,cCRNMaxLevelResolution], non-power of 2 OK, non-square OK
310   crn_uint32 m_height;  // [1,cCRNMaxLevelResolution], non-power of 2 OK, non-square OK
311   crn_uint32 m_levels;  // [1,cCRNMaxLevelResolution], non-power of 2 OK, non-square OK
312
313   crn_format m_format;  // Output pixel format.
314
315   crn_uint32 m_flags;  // see crn_comp_flags enum
316
317   // Array of pointers to 32bpp input images.
318   const crn_uint32* m_pImages[cCRNMaxFaces][cCRNMaxLevels];
319
320   // Target bitrate - if non-zero, the compressor will use an interpolative search to find the
321   // highest quality level that is <= the target bitrate. If it fails to find a bitrate high enough, it'll
322   // try disabling adaptive block sizes (cCRNCompFlagHierarchical flag) and redo the search. This process can be pretty slow.
323   float m_target_bitrate;
324
325   // Desired quality level.
326   // Currently, CRN and DDS quality levels are not compatible with eachother from an image quality standpoint.
327   crn_uint32 m_quality_level;  // [cCRNMinQualityLevel, cCRNMaxQualityLevel]
328
329   // DXTn compression parameters.
330   crn_uint32 m_dxt1a_alpha_threshold;
331   crn_dxt_quality m_dxt_quality;
332   crn_dxt_compressor_type m_dxt_compressor_type;
333
334   // Alpha channel's component. Defaults to 3.
335   crn_uint32 m_alpha_component;
336
337   // Various low-level CRN specific parameters.
338   float m_crn_adaptive_tile_color_psnr_derating;
339   float m_crn_adaptive_tile_alpha_psnr_derating;
340
341   crn_uint32 m_crn_color_endpoint_palette_size;  // [cCRNMinPaletteSize,cCRNMaxPaletteSize]
342   crn_uint32 m_crn_color_selector_palette_size;  // [cCRNMinPaletteSize,cCRNMaxPaletteSize]
343
344   crn_uint32 m_crn_alpha_endpoint_palette_size;  // [cCRNMinPaletteSize,cCRNMaxPaletteSize]
345   crn_uint32 m_crn_alpha_selector_palette_size;  // [cCRNMinPaletteSize,cCRNMaxPaletteSize]
346
347   // Number of helper threads to create during compression. 0=no threading.
348   crn_uint32 m_num_helper_threads;
349
350   // CRN userdata0 and userdata1 members, which are written directly to the header of the output file.
351   crn_uint32 m_userdata0;
352   crn_uint32 m_userdata1;
353
354   // User provided progress callback.
355   crn_progress_callback_func m_pProgress_func;
356   void* m_pProgress_func_data;
357 };
358
359 // Mipmap generator's mode.
360 enum crn_mip_mode {
361   cCRNMipModeUseSourceOrGenerateMips,  // Use source texture's mipmaps if it has any, otherwise generate new mipmaps
362   cCRNMipModeUseSourceMips,            // Use source texture's mipmaps if it has any, otherwise the output has no mipmaps
363   cCRNMipModeGenerateMips,             // Always generate new mipmaps
364   cCRNMipModeNoMips,                   // Output texture has no mipmaps
365
366   cCRNMipModeTotal,
367
368   cCRNModeForceDWORD = 0xFFFFFFFF
369 };
370
371 const char* crn_get_mip_mode_desc(crn_mip_mode m);
372 const char* crn_get_mip_mode_name(crn_mip_mode m);
373
374 // Mipmap generator's filter kernel.
375 enum crn_mip_filter {
376   cCRNMipFilterBox,
377   cCRNMipFilterTent,
378   cCRNMipFilterLanczos4,
379   cCRNMipFilterMitchell,
380   cCRNMipFilterKaiser,  // Kaiser=default mipmap filter
381
382   cCRNMipFilterTotal,
383
384   cCRNMipFilterForceDWORD = 0xFFFFFFFF
385 };
386
387 const char* crn_get_mip_filter_name(crn_mip_filter f);
388
389 // Mipmap generator's scale mode.
390 enum crn_scale_mode {
391   cCRNSMDisabled,
392   cCRNSMAbsolute,
393   cCRNSMRelative,
394   cCRNSMLowerPow2,
395   cCRNSMNearestPow2,
396   cCRNSMNextPow2,
397
398   cCRNSMTotal,
399
400   cCRNSMForceDWORD = 0xFFFFFFFF
401 };
402
403 const char* crn_get_scale_mode_desc(crn_scale_mode sm);
404
405 // Mipmap generator parameters.
406 struct crn_mipmap_params {
407   inline crn_mipmap_params() { clear(); }
408
409   inline void clear() {
410     m_size_of_obj = sizeof(*this);
411     m_mode = cCRNMipModeUseSourceOrGenerateMips;
412     m_filter = cCRNMipFilterKaiser;
413     m_gamma_filtering = true;
414     m_gamma = 2.2f;
415     // Default "blurriness" factor of .9 actually sharpens the output a little.
416     m_blurriness = .9f;
417     m_renormalize = false;
418     m_rtopmip = false;
419     m_tiled = false;
420     m_max_levels = cCRNMaxLevels;
421     m_min_mip_size = 1;
422
423     m_scale_mode = cCRNSMDisabled;
424     m_scale_x = 1.0f;
425     m_scale_y = 1.0f;
426
427     m_window_left = 0;
428     m_window_top = 0;
429     m_window_right = 0;
430     m_window_bottom = 0;
431
432     m_clamp_scale = false;
433     m_clamp_width = 0;
434     m_clamp_height = 0;
435   }
436
437   inline bool check() const { return true; }
438
439   inline bool operator==(const crn_mipmap_params& rhs) const {
440 #define CRNLIB_COMP(x)  \
441   do {                  \
442     if ((x) != (rhs.x)) \
443       return false;     \
444   } while (0)
445     CRNLIB_COMP(m_size_of_obj);
446     CRNLIB_COMP(m_mode);
447     CRNLIB_COMP(m_filter);
448     CRNLIB_COMP(m_gamma_filtering);
449     CRNLIB_COMP(m_gamma);
450     CRNLIB_COMP(m_blurriness);
451     CRNLIB_COMP(m_renormalize);
452     CRNLIB_COMP(m_rtopmip);
453     CRNLIB_COMP(m_tiled);
454     CRNLIB_COMP(m_max_levels);
455     CRNLIB_COMP(m_min_mip_size);
456     CRNLIB_COMP(m_scale_mode);
457     CRNLIB_COMP(m_scale_x);
458     CRNLIB_COMP(m_scale_y);
459     CRNLIB_COMP(m_window_left);
460     CRNLIB_COMP(m_window_top);
461     CRNLIB_COMP(m_window_right);
462     CRNLIB_COMP(m_window_bottom);
463     CRNLIB_COMP(m_clamp_scale);
464     CRNLIB_COMP(m_clamp_width);
465     CRNLIB_COMP(m_clamp_height);
466     return true;
467 #undef CRNLIB_COMP
468   }
469   crn_uint32 m_size_of_obj;
470
471   crn_mip_mode m_mode;
472   crn_mip_filter m_filter;
473
474   crn_bool m_gamma_filtering;
475   float m_gamma;
476
477   float m_blurriness;
478
479   crn_uint32 m_max_levels;
480   crn_uint32 m_min_mip_size;
481
482   crn_bool m_renormalize;
483   crn_bool m_rtopmip;
484   crn_bool m_tiled;
485
486   crn_scale_mode m_scale_mode;
487   float m_scale_x;
488   float m_scale_y;
489
490   crn_uint32 m_window_left;
491   crn_uint32 m_window_top;
492   crn_uint32 m_window_right;
493   crn_uint32 m_window_bottom;
494
495   crn_bool m_clamp_scale;
496   crn_uint32 m_clamp_width;
497   crn_uint32 m_clamp_height;
498 };
499
500 // -------- High-level helper function definitions for CDN/DDS compression.
501
502 #ifndef CRNLIB_MIN_ALLOC_ALIGNMENT
503 #define CRNLIB_MIN_ALLOC_ALIGNMENT sizeof(size_t) * 2
504 #endif
505
506 // Function to set an optional user provided memory allocation/reallocation/msize routines.
507 // By default, crnlib just uses malloc(), free(), etc. for all allocations.
508 typedef void* (*crn_realloc_func)(void* p, size_t size, size_t* pActual_size, bool movable, void* pUser_data);
509 typedef size_t (*crn_msize_func)(void* p, void* pUser_data);
510 void crn_set_memory_callbacks(crn_realloc_func pRealloc, crn_msize_func pMSize, void* pUser_data);
511
512 // Frees memory blocks allocated by crn_compress(), crn_decompress_crn_to_dds(), or crn_decompress_dds_to_images().
513 void crn_free_block(void* pBlock);
514
515 // Compresses a 32-bit/pixel texture to either: a regular DX9 DDS file, a "clustered" (or reduced entropy) DX9 DDS file, or a CRN file in memory.
516 // Input parameters:
517 //  comp_params is the compression parameters struct, defined above.
518 //  compressed_size will be set to the size of the returned memory block containing the output file.
519 //  The returned block must be freed by calling crn_free_block().
520 //  *pActual_quality_level will be set to the actual quality level used to compress the image. May be NULL.
521 //  *pActual_bitrate will be set to the output file's effective bitrate, possibly taking into account LZMA compression. May be NULL.
522 // Return value:
523 //  The compressed file data, or NULL on failure.
524 //  compressed_size will be set to the size of the returned memory buffer.
525 // Notes:
526 //  A "regular" DDS file is compressed using normal DXTn compression at the specified DXT quality level.
527 //  A "clustered" DDS file is compressed using clustered DXTn compression to either the target bitrate or the specified integer quality factor.
528 //  The output file is a standard DX9 format DDS file, except the compressor assumes you will be later losslessly compressing the DDS output file using the LZMA algorithm.
529 //  A texture is defined as an array of 1 or 6 "faces" (6 faces=cubemap), where each "face" consists of between [1,cCRNMaxLevels] mipmap levels.
530 //  Mipmap levels are simple 32-bit 2D images with a pitch of width*sizeof(uint32), arranged in the usual raster order (top scanline first).
531 //  The image pixels may be grayscale (YYYX bytes in memory), grayscale/alpha (YYYA in memory), 24-bit (RGBX in memory), or 32-bit (RGBA) colors (where "X"=don't care).
532 //  RGB color data is generally assumed to be in the sRGB colorspace. If not, be sure to clear the "cCRNCompFlagPerceptual" in the crn_comp_params struct!
533 void* crn_compress(const crn_comp_params& comp_params, crn_uint32& compressed_size, crn_uint32* pActual_quality_level = NULL, float* pActual_bitrate = NULL);
534
535 // Like the above function, except this function can also do things like generate mipmaps, and resize or crop the input texture before compression.
536 // The actual operations performed are controlled by the crn_mipmap_params struct members.
537 // Be sure to set the "m_gamma_filtering" member of crn_mipmap_params to false if the input texture is not sRGB.
538 void* crn_compress(const crn_comp_params& comp_params, const crn_mipmap_params& mip_params, crn_uint32& compressed_size, crn_uint32* pActual_quality_level = NULL, float* pActual_bitrate = NULL);
539
540 // Transcodes an entire CRN file to DDS using the crn_decomp.h header file library to do most of the heavy lifting.
541 // The output DDS file's format is guaranteed to be one of the DXTn formats in the crn_format enum.
542 // This is a fast operation, because the CRN format is explicitly designed to be efficiently transcodable to DXTn.
543 // For more control over decompression, see the lower-level helper functions in crn_decomp.h, which do not depend at all on crnlib.
544 void* crn_decompress_crn_to_dds(const void* pCRN_file_data, crn_uint32& file_size);
545
546 // Decompresses an entire DDS file in any supported format to uncompressed 32-bit/pixel image(s).
547 // See the crnlib::pixel_format enum in inc/dds_defs.h for a list of the supported DDS formats.
548 // You are responsible for freeing each image block, either by calling crn_free_all_images() or manually calling crn_free_block() on each image pointer.
549 struct crn_texture_desc {
550   crn_uint32 m_faces;
551   crn_uint32 m_width;
552   crn_uint32 m_height;
553   crn_uint32 m_levels;
554   crn_uint32 m_fmt_fourcc;  // Same as crnlib::pixel_format
555 };
556 bool crn_decompress_dds_to_images(const void* pDDS_file_data, crn_uint32 dds_file_size, crn_uint32** ppImages, crn_texture_desc& tex_desc);
557
558 // Frees all images allocated by crn_decompress_dds_to_images().
559 void crn_free_all_images(crn_uint32** ppImages, const crn_texture_desc& desc);
560
561 // -------- crn_format related helpers functions.
562
563 // Returns the FOURCC format equivalent to the specified crn_format.
564 crn_uint32 crn_get_format_fourcc(crn_format fmt);
565
566 // Returns the crn_format's bits per texel.
567 crn_uint32 crn_get_format_bits_per_texel(crn_format fmt);
568
569 // Returns the crn_format's number of bytes per block.
570 crn_uint32 crn_get_bytes_per_dxt_block(crn_format fmt);
571
572 // Returns the non-swizzled, basic DXTn version of the specified crn_format.
573 // This is the format you would supply D3D or OpenGL.
574 crn_format crn_get_fundamental_dxt_format(crn_format fmt);
575
576 // -------- String helpers.
577
578 // Converts a crn_file_type to a string.
579 const char* crn_get_file_type_ext(crn_file_type file_type);
580
581 // Converts a crn_format to a string.
582 const char* crn_get_format_string(crn_format fmt);
583
584 // Converts a crn_dxt_quality to a string.
585 const char* crn_get_dxt_quality_string(crn_dxt_quality q);
586
587 // -------- Low-level DXTn 4x4 block compressor API
588
589 // crnlib's DXTn endpoint optimizer actually supports any number of source pixels (i.e. from 1 to thousands, not just 16),
590 // but for simplicity this API only supports 4x4 texel blocks.
591 typedef void* crn_block_compressor_context_t;
592
593 // Create a DXTn block compressor.
594 // This function only supports the basic/nonswizzled "fundamental" formats: DXT1, DXT3, DXT5, DXT5A, DXN_XY and DXN_YX.
595 // Avoid calling this multiple times if you intend on compressing many blocks, because it allocates some memory.
596 crn_block_compressor_context_t crn_create_block_compressor(const crn_comp_params& params);
597
598 // Compresses a block of 16 pixels to the destination DXTn block.
599 // pDst_block should be 8 (for DXT1/DXT5A) or 16 bytes (all the others).
600 // pPixels should be an array of 16 crn_uint32's. Each crn_uint32 must be r,g,b,a (r is always first) in memory.
601 void crn_compress_block(crn_block_compressor_context_t pContext, const crn_uint32* pPixels, void* pDst_block);
602
603 // Frees a DXTn block compressor.
604 void crn_free_block_compressor(crn_block_compressor_context_t pContext);
605
606 // Unpacks a compressed block to pDst_pixels.
607 // pSrc_block should be 8 (for DXT1/DXT5A) or 16 bytes (all the others).
608 // pDst_pixel should be an array of 16 crn_uint32's. Each uint32 will be r,g,b,a (r is always first) in memory.
609 // crn_fmt should be one of the "fundamental" formats: DXT1, DXT3, DXT5, DXT5A, DXN_XY and DXN_YX.
610 // The various swizzled DXT5 formats (such as cCRNFmtDXT5_xGBR, etc.) will be unpacked as if they where plain DXT5.
611 // Returns false if the crn_fmt is invalid.
612 bool crn_decompress_block(const void* pSrc_block, crn_uint32* pDst_pixels, crn_format crn_fmt);
613
614 #endif  // CRNLIB_H
615
616 //------------------------------------------------------------------------------
617 //
618 // crnlib uses the ZLIB license:
619 // http://opensource.org/licenses/Zlib
620 //
621 // Copyright (c) 2010-2016 Richard Geldreich, Jr. and Binomial LLC
622 //
623 // This software is provided 'as-is', without any express or implied
624 // warranty.  In no event will the authors be held liable for any damages
625 // arising from the use of this software.
626 //
627 // Permission is granted to anyone to use this software for any purpose,
628 // including commercial applications, and to alter it and redistribute it
629 // freely, subject to the following restrictions:
630 //
631 // 1. The origin of this software must not be misrepresented; you must not
632 // claim that you wrote the original software. If you use this software
633 // in a product, an acknowledgment in the product documentation would be
634 // appreciated but is not required.
635 //
636 // 2. Altered source versions must be plainly marked as such, and must not be
637 // misrepresented as being the original software.
638 //
639 // 3. This notice may not be removed or altered from any source distribution.
640 //
641 //------------------------------------------------------------------------------