types.h (5167B)
1 /* Copyright (c) the JPEG XL Project Authors. All rights reserved. 2 * 3 * Use of this source code is governed by a BSD-style 4 * license that can be found in the LICENSE file. 5 */ 6 7 /** @addtogroup libjxl_common 8 * @{ 9 * @file types.h 10 * @brief Data types for the JPEG XL API, for both encoding and decoding. 11 */ 12 13 #ifndef JXL_TYPES_H_ 14 #define JXL_TYPES_H_ 15 16 #include <stddef.h> 17 #include <stdint.h> 18 19 #if defined(__cplusplus) || defined(c_plusplus) 20 extern "C" { 21 #endif 22 23 /** 24 * A portable @c bool replacement. 25 * 26 * ::JXL_BOOL is a "documentation" type: actually it is @c int, but in API it 27 * denotes a type, whose only values are ::JXL_TRUE and ::JXL_FALSE. 28 */ 29 #define JXL_BOOL int 30 /** Portable @c true replacement. */ 31 #define JXL_TRUE 1 32 /** Portable @c false replacement. */ 33 #define JXL_FALSE 0 34 /** Converts of bool-like value to either ::JXL_TRUE or ::JXL_FALSE. */ 35 #define TO_JXL_BOOL(C) (!!(C) ? JXL_TRUE : JXL_FALSE) 36 /** Converts JXL_BOOL to C++ bool. */ 37 #define FROM_JXL_BOOL(C) (static_cast<bool>(C)) 38 39 /** Data type for the sample values per channel per pixel. 40 */ 41 typedef enum { 42 /** Use 32-bit single-precision floating point values, with range 0.0-1.0 43 * (within gamut, may go outside this range for wide color gamut). Floating 44 * point output, either ::JXL_TYPE_FLOAT or ::JXL_TYPE_FLOAT16, is recommended 45 * for HDR and wide gamut images when color profile conversion is required. */ 46 JXL_TYPE_FLOAT = 0, 47 48 /** Use type uint8_t. May clip wide color gamut data. 49 */ 50 JXL_TYPE_UINT8 = 2, 51 52 /** Use type uint16_t. May clip wide color gamut data. 53 */ 54 JXL_TYPE_UINT16 = 3, 55 56 /** Use 16-bit IEEE 754 half-precision floating point values */ 57 JXL_TYPE_FLOAT16 = 5, 58 } JxlDataType; 59 60 /** Ordering of multi-byte data. 61 */ 62 typedef enum { 63 /** Use the endianness of the system, either little endian or big endian, 64 * without forcing either specific endianness. Do not use if pixel data 65 * should be exported to a well defined format. 66 */ 67 JXL_NATIVE_ENDIAN = 0, 68 /** Force little endian */ 69 JXL_LITTLE_ENDIAN = 1, 70 /** Force big endian */ 71 JXL_BIG_ENDIAN = 2, 72 } JxlEndianness; 73 74 /** Data type for the sample values per channel per pixel for the output buffer 75 * for pixels. This is not necessarily the same as the data type encoded in the 76 * codestream. The channels are interleaved per pixel. The pixels are 77 * organized row by row, left to right, top to bottom. 78 * TODO(lode): support different channel orders if needed (RGB, BGR, ...) 79 */ 80 typedef struct { 81 /** Amount of channels available in a pixel buffer. 82 * 1: single-channel data, e.g. grayscale or a single extra channel 83 * 2: single-channel + alpha 84 * 3: trichromatic, e.g. RGB 85 * 4: trichromatic + alpha 86 * TODO(lode): this needs finetuning. It is not yet defined how the user 87 * chooses output color space. CMYK+alpha needs 5 channels. 88 */ 89 uint32_t num_channels; 90 91 /** Data type of each channel. 92 */ 93 JxlDataType data_type; 94 95 /** Whether multi-byte data types are represented in big endian or little 96 * endian format. This applies to ::JXL_TYPE_UINT16 and ::JXL_TYPE_FLOAT. 97 */ 98 JxlEndianness endianness; 99 100 /** Align scanlines to a multiple of align bytes, or 0 to require no 101 * alignment at all (which has the same effect as value 1) 102 */ 103 size_t align; 104 } JxlPixelFormat; 105 106 /** Settings for the interpretation of UINT input and output buffers. 107 * (buffers using a FLOAT data type are not affected by this) 108 */ 109 typedef enum { 110 /** This is the default setting, where the encoder expects the input pixels 111 * to use the full range of the pixel format data type (e.g. for UINT16, the 112 * input range is 0 .. 65535 and the value 65535 is mapped to 1.0 when 113 * converting to float), and the decoder uses the full range to output 114 * pixels. If the bit depth in the basic info is different from this, the 115 * encoder expects the values to be rescaled accordingly (e.g. multiplied by 116 * 65535/4095 for a 12-bit image using UINT16 input data type). */ 117 JXL_BIT_DEPTH_FROM_PIXEL_FORMAT = 0, 118 119 /** If this setting is selected, the encoder expects the input pixels to be 120 * in the range defined by the bits_per_sample value of the basic info (e.g. 121 * for 12-bit images using UINT16 input data types, the allowed range is 122 * 0 .. 4095 and the value 4095 is mapped to 1.0 when converting to float), 123 * and the decoder outputs pixels in this range. */ 124 JXL_BIT_DEPTH_FROM_CODESTREAM = 1, 125 126 /** This setting can only be used in the decoder to select a custom range for 127 * pixel output */ 128 JXL_BIT_DEPTH_CUSTOM = 2, 129 } JxlBitDepthType; 130 131 /** Data type for describing the interpretation of the input and output buffers 132 * in terms of the range of allowed input and output pixel values. */ 133 typedef struct { 134 /** Bit depth setting, see comment on @ref JxlBitDepthType */ 135 JxlBitDepthType type; 136 137 /** Custom bits per sample */ 138 uint32_t bits_per_sample; 139 140 /** Custom exponent bits per sample */ 141 uint32_t exponent_bits_per_sample; 142 } JxlBitDepth; 143 144 /** Data type holding the 4-character type name of an ISOBMFF box. 145 */ 146 typedef char JxlBoxType[4]; 147 148 #if defined(__cplusplus) || defined(c_plusplus) 149 } 150 #endif 151 152 #endif /* JXL_TYPES_H_ */ 153 154 /** @}*/