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 /** @file codestream_header.h 8 * @brief Definitions of structs and enums for the metadata from the JPEG XL 9 * codestream headers (signature, metadata, preview dimensions, ...), excluding 10 * color encoding which is in color_encoding.h. 11 */ 12 13 #ifndef JXL_CODESTREAM_HEADER_H_ 14 #define JXL_CODESTREAM_HEADER_H_ 15 16 #include <stddef.h> 17 #include <stdint.h> 18 19 #include "jxl/color_encoding.h" 20 #include "jxl/types.h" 21 22 #if defined(__cplusplus) || defined(c_plusplus) 23 extern "C" { 24 #endif 25 26 /** Image orientation metadata. 27 * Values 1..8 match the EXIF definitions. 28 * The name indicates the operation to perform to transform from the encoded 29 * image to the display image. 30 */ 31 typedef enum { 32 JXL_ORIENT_IDENTITY = 1, 33 JXL_ORIENT_FLIP_HORIZONTAL = 2, 34 JXL_ORIENT_ROTATE_180 = 3, 35 JXL_ORIENT_FLIP_VERTICAL = 4, 36 JXL_ORIENT_TRANSPOSE = 5, 37 JXL_ORIENT_ROTATE_90_CW = 6, 38 JXL_ORIENT_ANTI_TRANSPOSE = 7, 39 JXL_ORIENT_ROTATE_90_CCW = 8, 40 } JxlOrientation; 41 42 /** Given type of an extra channel. 43 */ 44 typedef enum { 45 JXL_CHANNEL_ALPHA, 46 JXL_CHANNEL_DEPTH, 47 JXL_CHANNEL_SPOT_COLOR, 48 JXL_CHANNEL_SELECTION_MASK, 49 JXL_CHANNEL_BLACK, 50 JXL_CHANNEL_CFA, 51 JXL_CHANNEL_THERMAL, 52 JXL_CHANNEL_RESERVED0, 53 JXL_CHANNEL_RESERVED1, 54 JXL_CHANNEL_RESERVED2, 55 JXL_CHANNEL_RESERVED3, 56 JXL_CHANNEL_RESERVED4, 57 JXL_CHANNEL_RESERVED5, 58 JXL_CHANNEL_RESERVED6, 59 JXL_CHANNEL_RESERVED7, 60 JXL_CHANNEL_UNKNOWN, 61 JXL_CHANNEL_OPTIONAL 62 } JxlExtraChannelType; 63 64 /** The codestream preview header */ 65 typedef struct { 66 /** Preview width in pixels */ 67 uint32_t xsize; 68 69 /** Preview height in pixels */ 70 uint32_t ysize; 71 } JxlPreviewHeader; 72 73 /** The codestream animation header, optionally present in the beginning of 74 * the codestream, and if it is it applies to all animation frames, unlike 75 * JxlFrameHeader which applies to an individual frame. 76 */ 77 typedef struct { 78 /** Numerator of ticks per second of a single animation frame time unit */ 79 uint32_t tps_numerator; 80 81 /** Denominator of ticks per second of a single animation frame time unit */ 82 uint32_t tps_denominator; 83 84 /** Amount of animation loops, or 0 to repeat infinitely */ 85 uint32_t num_loops; 86 87 /** Whether animation time codes are present at animation frames in the 88 * codestream */ 89 JXL_BOOL have_timecodes; 90 } JxlAnimationHeader; 91 92 /** Basic image information. This information is available from the file 93 * signature and first part of the codestream header. 94 */ 95 typedef struct JxlBasicInfo { 96 /* TODO(lode): need additional fields for (transcoded) JPEG? For reusable 97 * fields orientation must be read from Exif APP1. For has_icc_profile: must 98 * look up where ICC profile is guaranteed to be in a JPEG file to be able to 99 * indicate this. */ 100 101 /* TODO(lode): make struct packed, and/or make this opaque struct with getter 102 * functions (still separate struct from opaque decoder) */ 103 104 /** Whether the codestream is embedded in the container format. If true, 105 * metadata information and extensions may be available in addition to the 106 * codestream. 107 */ 108 JXL_BOOL have_container; 109 110 /** Width of the image in pixels, before applying orientation. 111 */ 112 uint32_t xsize; 113 114 /** Height of the image in pixels, before applying orientation. 115 */ 116 uint32_t ysize; 117 118 /** Original image color channel bit depth. 119 */ 120 uint32_t bits_per_sample; 121 122 /** Original image color channel floating point exponent bits, or 0 if they 123 * are unsigned integer. For example, if the original data is half-precision 124 * (binary16) floating point, bits_per_sample is 16 and 125 * exponent_bits_per_sample is 5, and so on for other floating point 126 * precisions. 127 */ 128 uint32_t exponent_bits_per_sample; 129 130 /** Upper bound on the intensity level present in the image in nits. For 131 * unsigned integer pixel encodings, this is the brightness of the largest 132 * representable value. The image does not necessarily contain a pixel 133 * actually this bright. An encoder is allowed to set 255 for SDR images 134 * without computing a histogram. 135 */ 136 float intensity_target; 137 138 /** Lower bound on the intensity level present in the image. This may be 139 * loose, i.e. lower than the actual darkest pixel. When tone mapping, a 140 * decoder will map [min_nits, intensity_target] to the display range. 141 */ 142 float min_nits; 143 144 /** See the description of @see linear_below. 145 */ 146 JXL_BOOL relative_to_max_display; 147 148 /** The tone mapping will leave unchanged (linear mapping) any pixels whose 149 * brightness is strictly below this. The interpretation depends on 150 * relative_to_max_display. If true, this is a ratio [0, 1] of the maximum 151 * display brightness [nits], otherwise an absolute brightness [nits]. 152 */ 153 float linear_below; 154 155 /** Whether the data in the codestream is encoded in the original color 156 * profile that is attached to the codestream metadata header, or is 157 * encoded in an internally supported absolute color space (which the decoder 158 * can always convert to linear or non-linear sRGB or to XYB). If the original 159 * profile is used, the decoder outputs pixel data in the color space matching 160 * that profile, but doesn't convert it to any other color space. If the 161 * original profile is not used, the decoder only outputs the data as sRGB 162 * (linear if outputting to floating point, nonlinear with standard sRGB 163 * transfer function if outputting to unsigned integers) but will not convert 164 * it to to the original color profile. The decoder also does not convert to 165 * the target display color profile, but instead will always indicate which 166 * color profile the returned pixel data is encoded in when using @see 167 * JXL_COLOR_PROFILE_TARGET_DATA so that a CMS can be used to convert the 168 * data. 169 */ 170 JXL_BOOL uses_original_profile; 171 172 /** Indicates a preview image exists near the beginning of the codestream. 173 * The preview itself or its dimensions are not included in the basic info. 174 */ 175 JXL_BOOL have_preview; 176 177 /** Indicates animation frames exist in the codestream. The animation 178 * information is not included in the basic info. 179 */ 180 JXL_BOOL have_animation; 181 182 /** Image orientation, value 1-8 matching the values used by JEITA CP-3451C 183 * (Exif version 2.3). 184 */ 185 JxlOrientation orientation; 186 187 /** Number of color channels encoded in the image, this is either 1 for 188 * grayscale data, or 3 for colored data. This count does not include 189 * the alpha channel or other extra channels. To check presence of an alpha 190 * channel, such as in the case of RGBA color, check alpha_bits != 0. 191 * If and only if this is 1, the JxlColorSpace in the JxlColorEncoding is 192 * JXL_COLOR_SPACE_GRAY. 193 */ 194 uint32_t num_color_channels; 195 196 /** Number of additional image channels. This includes the main alpha channel, 197 * but can also include additional channels such as depth, additional alpha 198 * channels, spot colors, and so on. Information about the extra channels 199 * can be queried with JxlDecoderGetExtraChannelInfo. The main alpha channel, 200 * if it exists, also has its information available in the alpha_bits, 201 * alpha_exponent_bits and alpha_premultiplied fields in this JxlBasicInfo. 202 */ 203 uint32_t num_extra_channels; 204 205 /** Bit depth of the encoded alpha channel, or 0 if there is no alpha channel. 206 * If present, matches the alpha_bits value of the JxlExtraChannelInfo 207 * associated with this alpha channel. 208 */ 209 uint32_t alpha_bits; 210 211 /** Alpha channel floating point exponent bits, or 0 if they are unsigned. If 212 * present, matches the alpha_bits value of the JxlExtraChannelInfo associated 213 * with this alpha channel. integer. 214 */ 215 uint32_t alpha_exponent_bits; 216 217 /** Whether the alpha channel is premultiplied. Only used if there is a main 218 * alpha channel. Matches the alpha_premultiplied value of the 219 * JxlExtraChannelInfo associated with this alpha channel. 220 */ 221 JXL_BOOL alpha_premultiplied; 222 223 /** Dimensions of encoded preview image, only used if have_preview is 224 * JXL_TRUE. 225 */ 226 JxlPreviewHeader preview; 227 228 /** Animation header with global animation properties for all frames, only 229 * used if have_animation is JXL_TRUE. 230 */ 231 JxlAnimationHeader animation; 232 233 /** Padding for forwards-compatibility, in case more fields are exposed 234 * in a future version of the library. 235 */ 236 uint8_t padding[108]; 237 } JxlBasicInfo; 238 239 /** Information for a single extra channel. 240 */ 241 typedef struct { 242 /** Given type of an extra channel. 243 */ 244 JxlExtraChannelType type; 245 246 /** Total bits per sample for this channel. 247 */ 248 uint32_t bits_per_sample; 249 250 /** Floating point exponent bits per channel, or 0 if they are unsigned 251 * integer. 252 */ 253 uint32_t exponent_bits_per_sample; 254 255 /** The exponent the channel is downsampled by on each axis. 256 * TODO(lode): expand this comment to match the JPEG XL specification, 257 * specify how to upscale, how to round the size computation, and to which 258 * extra channels this field applies. 259 */ 260 uint32_t dim_shift; 261 262 /** Length of the extra channel name in bytes, or 0 if no name. 263 * Excludes null termination character. 264 */ 265 uint32_t name_length; 266 267 /** Whether alpha channel uses premultiplied alpha. Only applicable if 268 * type is JXL_CHANNEL_ALPHA. 269 */ 270 JXL_BOOL alpha_premultiplied; 271 272 /** Spot color of the current spot channel in linear RGBA. Only applicable if 273 * type is JXL_CHANNEL_SPOT_COLOR. 274 */ 275 float spot_color[4]; 276 277 /** Only applicable if type is JXL_CHANNEL_CFA. 278 * TODO(lode): add comment about the meaning of this field. 279 */ 280 uint32_t cfa_channel; 281 } JxlExtraChannelInfo; 282 283 /* TODO(lode): add API to get the codestream header extensions. */ 284 /** Extensions in the codestream header. */ 285 typedef struct { 286 /** Extension bits. */ 287 uint64_t extensions; 288 } JxlHeaderExtensions; 289 290 /** The header of one displayed frame. */ 291 typedef struct { 292 /** How long to wait after rendering in ticks. The duration in seconds of a 293 * tick is given by tps_numerator and tps_denominator in JxlAnimationHeader. 294 */ 295 uint32_t duration; 296 297 /** SMPTE timecode of the current frame in form 0xHHMMSSFF, or 0. The bits are 298 * interpreted from most-significant to least-significant as hour, minute, 299 * second, and frame. If timecode is nonzero, it is strictly larger than that 300 * of a previous frame with nonzero duration. These values are only available 301 * if have_timecodes in JxlAnimationHeader is JXL_TRUE. 302 * This value is only used if have_timecodes in JxlAnimationHeader is 303 * JXL_TRUE. 304 */ 305 uint32_t timecode; 306 307 /** Length of the frame name in bytes, or 0 if no name. 308 * Excludes null termination character. 309 */ 310 uint32_t name_length; 311 312 /** Indicates this is the last animation frame. 313 */ 314 JXL_BOOL is_last; 315 } JxlFrameHeader; 316 317 #if defined(__cplusplus) || defined(c_plusplus) 318 } 319 #endif 320 321 #endif /* JXL_CODESTREAM_HEADER_H_ */ 322