FFmpeg 9.1
Loading...
Searching...
No Matches
raw_color_params.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2026 Lynne <dev@lynne.ee>
3 *
4 * This file is part of FFmpeg.
5 *
6 * FFmpeg is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * FFmpeg is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with FFmpeg; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 */
20
21#ifndef AVUTIL_RAW_COLOR_PARAMS_H
22#define AVUTIL_RAW_COLOR_PARAMS_H
23
24#include <stddef.h>
25#include <stdint.h>
26
27#include "frame.h"
28#include "rational.h"
29
32
33 /**
34 * The union is valid when interpreted as AVProResRawColorParams
35 * (codec.prores_raw).
36 */
38
39 /**
40 * The union is valid when interpreted as AVRW2RawColorParams
41 * (codec.rw2).
42 */
44};
45
46/**
47 * ProRes RAW per-frame color transform, parsed from the prrf frame header.
48 *
49 * The correct rendering pipeline is:
50 * -> (sample - black_level) / (white_level - black_level)
51 * -> per-channel white balance (wb_red, 1.0 for G, wb_blue) pre-debayer
52 * -> debayer
53 * -> color_matrix (camera RGB -> CIE 1931 XYZ relative to D65)
54 * -> gain (scene-linear scale)
55 *
56 * Black/white levels live on the outer AVRawColorParams. The matrix output
57 * is linear-light CIE XYZ D65; convert to a working RGB space downstream.
58 *
59 * @note The struct must be allocated as part of AVRawColorParams using
60 * av_raw_color_params_alloc(). Its size is not a part of the public ABI.
61 */
62typedef struct AVProResRawColorParams {
63 /**
64 * White balance multiplier for the red channel, applied pre-debayer.
65 */
67
68 /**
69 * White balance multiplier for the blue channel, applied pre-debayer.
70 * (The green channel is implicit 1.0 for ProRes RAW)
71 */
73
74 /**
75 * 3x3 row-major color matrix from camera RGB to linear-light CIE 1931
76 * XYZ relative to the D65 illuminant, applied post-debayer.
77 * out[i] = sum_j color_matrix[i][j] * in[j].
78 */
80
81 /**
82 * Post-matrix scene-linear scaling factor. Encodes highlight headroom the
83 * encoder reserved; multiply the matrixed values by this to recover
84 * scene-linear light.
85 */
88
89/**
90 * Panasonic RW2 as-shot white balance, from the file's WB level tags.
91 *
92 * The file carries no camera matrix. After white balance and debayering,
93 * camera RGB needs a profile for the camera model, which the EXIF side data
94 * names.
95 *
96 * @note The struct must be allocated as part of AVRawColorParams using
97 * av_raw_color_params_alloc(). Its size is not a part of the public ABI.
98 */
99typedef struct AVRW2RawColorParams {
100 /**
101 * White balance multiplier for the red channel, applied pre-debayer.
102 */
104
105 /**
106 * White balance multiplier for the blue channel, applied pre-debayer.
107 * The green channel is implicitly 1.0.
108 */
111
112/**
113 * Per-frame color information for a RAW camera codec. Carried as side data of
114 * type AV_FRAME_DATA_RAW_COLOR_PARAMS.
115 *
116 * The outer struct carries the fields every RAW codec exposes: the sensor's
117 * valid sample range and the white-balance correlated color temperature.
118 * The codec union holds the codec-specific transform parameters; `type`
119 * selects which member of the union is valid.
120 *
121 * The codec-specific transform (color_matrix or equivalent) always lands in
122 * linear-light CIE 1931 XYZ relative to the D65 illuminant, cameras don't
123 * have standard primaries, so XYZ is the only common target.
124 *
125 * @note The struct must be allocated using av_raw_color_params_alloc() or
126 * av_raw_color_params_create_side_data(). Its size is not a part of the
127 * public ABI.
128 */
129typedef struct AVRawColorParams {
130 /**
131 * Selects which member of `codec` is valid.
132 */
134
135 /**
136 * Lowest valid raw sample code (sensor black point)
137 */
139
140 /**
141 * Highest valid raw sample code (sensor white point)
142 */
144
145 /**
146 * Color temperature in Kelvin from with the camera's white balance.
147 * Informational; the math uses the codec-specific white-balance fields.
148 * 0 if not signaled.
149 */
150 uint32_t wb_cct;
151
152 /**
153 * Additional codec-specific fields.
154 */
155 union {
160
161/**
162 * Allocate an AVRawColorParams structure and zero-initialize it.
163 *
164 * @param size if non-NULL, set to sizeof(AVRawColorParams)
165 * @return the newly allocated struct or NULL on failure
166 */
168
169/**
170 * Allocate and add an AVRawColorParams structure to an existing AVFrame as
171 * AV_FRAME_DATA_RAW_COLOR_PARAMS side data.
172 *
173 * @return the newly allocated struct, or NULL on failure
174 */
176
177#endif /* AVUTIL_RAW_COLOR_PARAMS_H */
static AVFrame * frame
reference-counted frame API
Utilities for rational number calculation.
AVRawColorParamsType
@ AV_RAW_COLOR_PARAMS_NONE
@ AV_RAW_COLOR_PARAMS_RW2
The union is valid when interpreted as AVRW2RawColorParams (codec.rw2).
@ AV_RAW_COLOR_PARAMS_PRORES_RAW
The union is valid when interpreted as AVProResRawColorParams (codec.prores_raw).
AVRawColorParams * av_raw_color_params_create_side_data(AVFrame *frame)
Allocate and add an AVRawColorParams structure to an existing AVFrame as AV_FRAME_DATA_RAW_COLOR_PARA...
AVRawColorParams * av_raw_color_params_alloc(size_t *size)
Allocate an AVRawColorParams structure and zero-initialize it.
This structure describes decoded (raw) audio or video data.
Definition frame.h:479
ProRes RAW per-frame color transform, parsed from the prrf frame header.
AVRational wb_red
White balance multiplier for the red channel, applied pre-debayer.
AVRational color_matrix[3][3]
3x3 row-major color matrix from camera RGB to linear-light CIE 1931 XYZ relative to the D65 illuminan...
AVRational wb_blue
White balance multiplier for the blue channel, applied pre-debayer.
AVRational gain
Post-matrix scene-linear scaling factor.
Panasonic RW2 as-shot white balance, from the file's WB level tags.
AVRational wb_red
White balance multiplier for the red channel, applied pre-debayer.
AVRational wb_blue
White balance multiplier for the blue channel, applied pre-debayer.
Rational number (pair of numerator and denominator).
Definition rational.h:58
Per-frame color information for a RAW camera codec.
AVProResRawColorParams prores_raw
AVRational black_level
Lowest valid raw sample code (sensor black point).
AVRW2RawColorParams rw2
enum AVRawColorParamsType type
Selects which member of codec is valid.
union AVRawColorParams::@064000052037250306123267111255172234366153040136 codec
Additional codec-specific fields.
AVRational white_level
Highest valid raw sample code (sensor white point).
uint32_t wb_cct
Color temperature in Kelvin from with the camera's white balance.