codestream_header.h (15157B)
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_metadata 8 * @{ 9 * @file codestream_header.h 10 * @brief Definitions of structs and enums for the metadata from the JPEG XL 11 * codestream headers (signature, metadata, preview dimensions, ...), excluding 12 * color encoding which is in color_encoding.h. 13 */ 14 15 #ifndef JXL_CODESTREAM_HEADER_H_ 16 #define JXL_CODESTREAM_HEADER_H_ 17 18 #include <jxl/types.h> 19 #include <stddef.h> 20 #include <stdint.h> 21 22 #ifdef __cplusplus 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 @ref 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 { 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 * Leaving this set to its default of 0 lets libjxl choose a sensible default 136 * value based on the color encoding. 137 */ 138 float intensity_target; 139 140 /** Lower bound on the intensity level present in the image. This may be 141 * loose, i.e. lower than the actual darkest pixel. When tone mapping, a 142 * decoder will map [min_nits, intensity_target] to the display range. 143 */ 144 float min_nits; 145 146 /** See the description of @see linear_below. 147 */ 148 JXL_BOOL relative_to_max_display; 149 150 /** The tone mapping will leave unchanged (linear mapping) any pixels whose 151 * brightness is strictly below this. The interpretation depends on 152 * relative_to_max_display. If true, this is a ratio [0, 1] of the maximum 153 * display brightness [nits], otherwise an absolute brightness [nits]. 154 */ 155 float linear_below; 156 157 /** Whether the data in the codestream is encoded in the original color 158 * profile that is attached to the codestream metadata header, or is 159 * encoded in an internally supported absolute color space (which the decoder 160 * can always convert to linear or non-linear sRGB or to XYB). If the original 161 * profile is used, the decoder outputs pixel data in the color space matching 162 * that profile, but doesn't convert it to any other color space. If the 163 * original profile is not used, the decoder only outputs the data as sRGB 164 * (linear if outputting to floating point, nonlinear with standard sRGB 165 * transfer function if outputting to unsigned integers) but will not convert 166 * it to to the original color profile. The decoder also does not convert to 167 * the target display color profile. To convert the pixel data produced by 168 * the decoder to the original color profile, one of the JxlDecoderGetColor* 169 * functions needs to be called with 170 * ::JXL_COLOR_PROFILE_TARGET_DATA to get the color profile of the decoder 171 * output, and then an external CMS can be used for conversion. Note that for 172 * lossy compression, this should be set to false for most use cases, and if 173 * needed, the image should be converted to the original color profile after 174 * decoding, as described above. 175 */ 176 JXL_BOOL uses_original_profile; 177 178 /** Indicates a preview image exists near the beginning of the codestream. 179 * The preview itself or its dimensions are not included in the basic info. 180 */ 181 JXL_BOOL have_preview; 182 183 /** Indicates animation frames exist in the codestream. The animation 184 * information is not included in the basic info. 185 */ 186 JXL_BOOL have_animation; 187 188 /** Image orientation, value 1-8 matching the values used by JEITA CP-3451C 189 * (Exif version 2.3). 190 */ 191 JxlOrientation orientation; 192 193 /** Number of color channels encoded in the image, this is either 1 for 194 * grayscale data, or 3 for colored data. This count does not include 195 * the alpha channel or other extra channels. To check presence of an alpha 196 * channel, such as in the case of RGBA color, check alpha_bits != 0. 197 * If and only if this is 1, the @ref JxlColorSpace in the @ref 198 * JxlColorEncoding is 199 * ::JXL_COLOR_SPACE_GRAY. 200 */ 201 uint32_t num_color_channels; 202 203 /** Number of additional image channels. This includes the main alpha channel, 204 * but can also include additional channels such as depth, additional alpha 205 * channels, spot colors, and so on. Information about the extra channels 206 * can be queried with @ref JxlDecoderGetExtraChannelInfo. The main alpha 207 * channel, if it exists, also has its information available in the 208 * alpha_bits, alpha_exponent_bits and alpha_premultiplied fields in this @ref 209 * JxlBasicInfo. 210 */ 211 uint32_t num_extra_channels; 212 213 /** Bit depth of the encoded alpha channel, or 0 if there is no alpha channel. 214 * If present, matches the alpha_bits value of the JxlExtraChannelInfo 215 * associated with this alpha channel. 216 */ 217 uint32_t alpha_bits; 218 219 /** Alpha channel floating point exponent bits, or 0 if they are unsigned. If 220 * present, matches the alpha_bits value of the JxlExtraChannelInfo associated 221 * with this alpha channel. integer. 222 */ 223 uint32_t alpha_exponent_bits; 224 225 /** Whether the alpha channel is premultiplied. Only used if there is a main 226 * alpha channel. Matches the alpha_premultiplied value of the 227 * JxlExtraChannelInfo associated with this alpha channel. 228 */ 229 JXL_BOOL alpha_premultiplied; 230 231 /** Dimensions of encoded preview image, only used if have_preview is 232 * JXL_TRUE. 233 */ 234 JxlPreviewHeader preview; 235 236 /** Animation header with global animation properties for all frames, only 237 * used if have_animation is JXL_TRUE. 238 */ 239 JxlAnimationHeader animation; 240 241 /** Intrinsic width of the image. 242 * The intrinsic size can be different from the actual size in pixels 243 * (as given by xsize and ysize) and it denotes the recommended dimensions 244 * for displaying the image, i.e. applications are advised to resample the 245 * decoded image to the intrinsic dimensions. 246 */ 247 uint32_t intrinsic_xsize; 248 249 /** Intrinsic height of the image. 250 * The intrinsic size can be different from the actual size in pixels 251 * (as given by xsize and ysize) and it denotes the recommended dimensions 252 * for displaying the image, i.e. applications are advised to resample the 253 * decoded image to the intrinsic dimensions. 254 */ 255 uint32_t intrinsic_ysize; 256 257 /** Padding for forwards-compatibility, in case more fields are exposed 258 * in a future version of the library. 259 */ 260 uint8_t padding[100]; 261 } JxlBasicInfo; 262 263 /** Information for a single extra channel. 264 */ 265 typedef struct { 266 /** Given type of an extra channel. 267 */ 268 JxlExtraChannelType type; 269 270 /** Total bits per sample for this channel. 271 */ 272 uint32_t bits_per_sample; 273 274 /** Floating point exponent bits per channel, or 0 if they are unsigned 275 * integer. 276 */ 277 uint32_t exponent_bits_per_sample; 278 279 /** The exponent the channel is downsampled by on each axis. 280 * TODO(lode): expand this comment to match the JPEG XL specification, 281 * specify how to upscale, how to round the size computation, and to which 282 * extra channels this field applies. 283 */ 284 uint32_t dim_shift; 285 286 /** Length of the extra channel name in bytes, or 0 if no name. 287 * Excludes null termination character. 288 */ 289 uint32_t name_length; 290 291 /** Whether alpha channel uses premultiplied alpha. Only applicable if 292 * type is JXL_CHANNEL_ALPHA. 293 */ 294 JXL_BOOL alpha_premultiplied; 295 296 /** Spot color of the current spot channel in linear RGBA. Only applicable if 297 * type is JXL_CHANNEL_SPOT_COLOR. 298 */ 299 float spot_color[4]; 300 301 /** Only applicable if type is JXL_CHANNEL_CFA. 302 * TODO(lode): add comment about the meaning of this field. 303 */ 304 uint32_t cfa_channel; 305 } JxlExtraChannelInfo; 306 307 /* TODO(lode): add API to get the codestream header extensions. */ 308 /** Extensions in the codestream header. */ 309 typedef struct { 310 /** Extension bits. */ 311 uint64_t extensions; 312 } JxlHeaderExtensions; 313 314 /** Frame blend modes. 315 * When decoding, if coalescing is enabled (default), this can be ignored. 316 */ 317 typedef enum { 318 JXL_BLEND_REPLACE = 0, 319 JXL_BLEND_ADD = 1, 320 JXL_BLEND_BLEND = 2, 321 JXL_BLEND_MULADD = 3, 322 JXL_BLEND_MUL = 4, 323 } JxlBlendMode; 324 325 /** The information about blending the color channels or a single extra channel. 326 * When decoding, if coalescing is enabled (default), this can be ignored and 327 * the blend mode is considered to be JXL_BLEND_REPLACE. 328 * When encoding, these settings apply to the pixel data given to the encoder. 329 */ 330 typedef struct { 331 /** Blend mode. 332 */ 333 JxlBlendMode blendmode; 334 /** Reference frame ID to use as the 'bottom' layer (0-3). 335 */ 336 uint32_t source; 337 /** Which extra channel to use as the 'alpha' channel for blend modes 338 * JXL_BLEND_BLEND and JXL_BLEND_MULADD. 339 */ 340 uint32_t alpha; 341 /** Clamp values to [0,1] for the purpose of blending. 342 */ 343 JXL_BOOL clamp; 344 } JxlBlendInfo; 345 346 /** The information about layers. 347 * When decoding, if coalescing is enabled (default), this can be ignored. 348 * When encoding, these settings apply to the pixel data given to the encoder, 349 * the encoder could choose an internal representation that differs. 350 */ 351 typedef struct { 352 /** Whether cropping is applied for this frame. When decoding, if false, 353 * crop_x0 and crop_y0 are set to zero, and xsize and ysize to the main 354 * image dimensions. When encoding and this is false, those fields are 355 * ignored. When decoding, if coalescing is enabled (default), this is always 356 * false, regardless of the internal encoding in the JPEG XL codestream. 357 */ 358 JXL_BOOL have_crop; 359 360 /** Horizontal offset of the frame (can be negative). 361 */ 362 int32_t crop_x0; 363 364 /** Vertical offset of the frame (can be negative). 365 */ 366 int32_t crop_y0; 367 368 /** Width of the frame (number of columns). 369 */ 370 uint32_t xsize; 371 372 /** Height of the frame (number of rows). 373 */ 374 uint32_t ysize; 375 376 /** The blending info for the color channels. Blending info for extra channels 377 * has to be retrieved separately using JxlDecoderGetExtraChannelBlendInfo. 378 */ 379 JxlBlendInfo blend_info; 380 381 /** After blending, save the frame as reference frame with this ID (0-3). 382 * Special case: if the frame duration is nonzero, ID 0 means "will not be 383 * referenced in the future". This value is not used for the last frame. 384 * When encoding, ID 3 is reserved to frames that are generated internally by 385 * the encoder, and should not be used by applications. 386 */ 387 uint32_t save_as_reference; 388 } JxlLayerInfo; 389 390 /** The header of one displayed frame or non-coalesced layer. */ 391 typedef struct { 392 /** How long to wait after rendering in ticks. The duration in seconds of a 393 * tick is given by tps_numerator and tps_denominator in @ref 394 * JxlAnimationHeader. 395 */ 396 uint32_t duration; 397 398 /** SMPTE timecode of the current frame in form 0xHHMMSSFF, or 0. The bits are 399 * interpreted from most-significant to least-significant as hour, minute, 400 * second, and frame. If timecode is nonzero, it is strictly larger than that 401 * of a previous frame with nonzero duration. These values are only available 402 * if have_timecodes in @ref JxlAnimationHeader is ::JXL_TRUE. 403 * This value is only used if have_timecodes in @ref JxlAnimationHeader is 404 * ::JXL_TRUE. 405 */ 406 uint32_t timecode; 407 408 /** Length of the frame name in bytes, or 0 if no name. 409 * Excludes null termination character. This value is set by the decoder. 410 * For the encoder, this value is ignored and @ref JxlEncoderSetFrameName is 411 * used instead to set the name and the length. 412 */ 413 uint32_t name_length; 414 415 /** Indicates this is the last animation frame. This value is set by the 416 * decoder to indicate no further frames follow. For the encoder, it is not 417 * required to set this value and it is ignored, @ref JxlEncoderCloseFrames is 418 * used to indicate the last frame to the encoder instead. 419 */ 420 JXL_BOOL is_last; 421 422 /** Information about the layer in case of no coalescing. 423 */ 424 JxlLayerInfo layer_info; 425 } JxlFrameHeader; 426 427 #ifdef __cplusplus 428 } 429 #endif 430 431 #endif /* JXL_CODESTREAM_HEADER_H_ */ 432 433 /** @}*/