FFmpeg
dovi_rpu.h
Go to the documentation of this file.
1 /*
2  * Dolby Vision RPU decoder
3  *
4  * Copyright (C) 2021 Jan Ekström
5  * Copyright (C) 2021 Niklas Haas
6  *
7  * This file is part of FFmpeg.
8  *
9  * FFmpeg is free software; you can redistribute it and/or
10  * modify it under the terms of the GNU Lesser General Public
11  * License as published by the Free Software Foundation; either
12  * version 2.1 of the License, or (at your option) any later version.
13  *
14  * FFmpeg is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17  * Lesser General Public License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public
20  * License along with FFmpeg; if not, write to the Free Software
21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
22  */
23 
24 #ifndef AVCODEC_DOVI_RPU_H
25 #define AVCODEC_DOVI_RPU_H
26 
27 #include "libavutil/dovi_meta.h"
28 #include "libavutil/frame.h"
29 #include "avcodec.h"
30 
31 #define DOVI_MAX_DM_ID 15
32 typedef struct DOVIContext {
33  void *logctx;
34 
35  /**
36  * Enable tri-state. For encoding only. FF_DOVI_AUTOMATIC enables Dolby
37  * Vision only if avctx->decoded_side_data contains an AVDOVIMetadata.
38  */
39 #define FF_DOVI_AUTOMATIC -1
40  int enable;
41 
42  /**
43  * Currently active dolby vision configuration, or {0} for none.
44  * Set by the user when decoding. Generated by ff_dovi_configure()
45  * when encoding.
46  *
47  * Note: sizeof(cfg) is not part of the libavutil ABI, so users should
48  * never pass &cfg to any other library calls. This is included merely as
49  * a way to look up the values of fields known at compile time.
50  */
52 
53  /**
54  * Currently active RPU data header, updates on every ff_dovi_rpu_parse()
55  * or ff_dovi_rpu_generate().
56  */
58 
59  /**
60  * Currently active data mappings, or NULL. Points into memory owned by the
61  * corresponding rpu/vdr_ref, which becomes invalid on the next call to
62  * ff_dovi_rpu_parse() or ff_dovi_rpu_generate().
63  */
66 
67  /**
68  * Currently active extension blocks, updates on every ff_dovi_rpu_parse()
69  * or ff_dovi_rpu_generate().
70  */
73 
74  /**
75  * Private fields internal to dovi_rpu.c
76  */
77  AVDOVIColorMetadata *dm; ///< RefStruct
78  AVDOVIDataMapping *vdr[DOVI_MAX_DM_ID+1]; ///< RefStruct references
79  uint8_t *rpu_buf; ///< temporary buffer
80  unsigned rpu_buf_sz;
81 
82 } DOVIContext;
83 
85 
86 /**
87  * Completely reset a DOVIContext, preserving only logctx.
88  */
90 
91 /**
92  * Partially reset the internal state. Resets per-frame state, but preserves
93  * the stream-wide configuration record.
94  */
96 
97 /**
98  * Parse the contents of a Dovi RPU NAL and update the parsed values in the
99  * DOVIContext struct.
100  *
101  * Returns 0 or an error code.
102  *
103  * Note: `DOVIContext.cfg` should be initialized before calling into this
104  * function. If not done, the profile will be guessed according to HEVC
105  * semantics.
106  */
107 int ff_dovi_rpu_parse(DOVIContext *s, const uint8_t *rpu, size_t rpu_size,
108  int err_recognition);
109 
110 /**
111  * Attach the decoded AVDOVIMetadata as side data to an AVFrame.
112  */
114 
115 /**
116  * Configure the encoder for Dolby Vision encoding. Generates a configuration
117  * record in s->cfg, and attaches it to avctx->coded_side_data. Sets the correct
118  * profile and compatibility ID based on the tagged AVCodecContext colorspace
119  * metadata, and the correct level based on the resolution and tagged framerate.
120  *
121  * Returns 0 or a negative error code.
122  */
124 
125 /**
126  * Synthesize a Dolby Vision RPU reflecting the current state. Note that this
127  * assumes all previous calls to `ff_dovi_rpu_generate` have been appropriately
128  * signalled, i.e. it will not re-send already transmitted redundant data.
129  *
130  * Mutates the internal state of DOVIContext to reflect the change.
131  * Returns 0 or a negative error code.
132  *
133  * This generates a fully formed RPU ready for inclusion in the bitstream,
134  * including the EMDF header (profile 10) or NAL encapsulation (otherwise).
135  */
136 int ff_dovi_rpu_generate(DOVIContext *s, const AVDOVIMetadata *metadata,
137  uint8_t **out_rpu, int *out_size);
138 
139 
140 /***************************************************
141  * The following section is for internal use only. *
142  ***************************************************/
143 
144 enum {
145  RPU_COEFF_FIXED = 0,
146  RPU_COEFF_FLOAT = 1,
147 };
148 
149 /**
150  * Internal helper function to guess the correct DV profile for HEVC.
151  *
152  * Returns the profile number or 0 if unknown.
153  */
155 
156 /* Default values for AVDOVIColorMetadata */
158 
159 #endif /* AVCODEC_DOVI_RPU_H */
DOVIContext::ext_blocks
AVDOVIDmData * ext_blocks
Currently active extension blocks, updates on every ff_dovi_rpu_parse() or ff_dovi_rpu_generate().
Definition: dovi_rpu.h:71
DOVIContext::cfg
AVDOVIDecoderConfigurationRecord cfg
Currently active dolby vision configuration, or {0} for none.
Definition: dovi_rpu.h:51
ff_dovi_ctx_replace
void ff_dovi_ctx_replace(DOVIContext *s, const DOVIContext *s0)
Definition: dovi_rpu.c:58
DOVI_MAX_DM_ID
#define DOVI_MAX_DM_ID
Definition: dovi_rpu.h:31
ff_dovi_rpu_parse
int ff_dovi_rpu_parse(DOVIContext *s, const uint8_t *rpu, size_t rpu_size, int err_recognition)
Parse the contents of a Dovi RPU NAL and update the parsed values in the DOVIContext struct.
Definition: dovi_rpudec.c:304
out_size
int out_size
Definition: movenc.c:56
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:374
ff_dovi_color_default
const AVDOVIColorMetadata ff_dovi_color_default
Definition: dovi_rpu.c:93
AVDOVIRpuDataHeader
Dolby Vision RPU data header.
Definition: dovi_meta.h:78
DOVIContext
Definition: dovi_rpu.h:32
ff_dovi_configure
int ff_dovi_configure(DOVIContext *s, AVCodecContext *avctx)
Configure the encoder for Dolby Vision encoding.
Definition: dovi_rpuenc.c:55
RPU_COEFF_FLOAT
@ RPU_COEFF_FLOAT
Definition: dovi_rpu.h:148
AVDOVIDmData
Dolby Vision metadata extension block.
Definition: dovi_meta.h:299
AVDOVIMetadata
Combined struct representing a combination of header, mapping and color metadata, for attaching to fr...
Definition: dovi_meta.h:326
s
#define s(width, name)
Definition: cbs_vp9.c:198
DOVIContext::mapping
const AVDOVIDataMapping * mapping
Currently active data mappings, or NULL.
Definition: dovi_rpu.h:64
ff_dovi_rpu_generate
int ff_dovi_rpu_generate(DOVIContext *s, const AVDOVIMetadata *metadata, uint8_t **out_rpu, int *out_size)
Synthesize a Dolby Vision RPU reflecting the current state.
Definition: dovi_rpuenc.c:437
DOVIContext::vdr
AVDOVIDataMapping * vdr[DOVI_MAX_DM_ID+1]
RefStruct references.
Definition: dovi_rpu.h:78
DOVIContext::color
const AVDOVIColorMetadata * color
Definition: dovi_rpu.h:65
DOVIContext::rpu_buf_sz
unsigned rpu_buf_sz
Definition: dovi_rpu.h:80
ff_dovi_attach_side_data
int ff_dovi_attach_side_data(DOVIContext *s, AVFrame *frame)
Attach the decoded AVDOVIMetadata as side data to an AVFrame.
Definition: dovi_rpudec.c:33
ff_dovi_ctx_flush
void ff_dovi_ctx_flush(DOVIContext *s)
Partially reset the internal state.
Definition: dovi_rpu.c:42
frame.h
DOVIContext::header
AVDOVIRpuDataHeader header
Currently active RPU data header, updates on every ff_dovi_rpu_parse() or ff_dovi_rpu_generate().
Definition: dovi_rpu.h:57
avcodec.h
frame
these buffered frames must be flushed immediately if a new input produces new the filter must not call request_frame to get more It must just process the frame or queue it The task of requesting more frames is left to the filter s request_frame method or the application If a filter has several the filter must be ready for frames arriving randomly on any input any filter with several inputs will most likely require some kind of queuing mechanism It is perfectly acceptable to have a limited queue and to drop frames when the inputs are too unbalanced request_frame For filters that do not use the this method is called when a frame is wanted on an output For a it should directly call filter_frame on the corresponding output For a if there are queued frames already one of these frames should be pushed If the filter should request a frame on one of its repeatedly until at least one frame has been pushed Return or at least make progress towards producing a frame
Definition: filter_design.txt:264
dovi_meta.h
AVCodecContext
main external API structure.
Definition: avcodec.h:445
RPU_COEFF_FIXED
@ RPU_COEFF_FIXED
Definition: dovi_rpu.h:147
DOVIContext::dm
AVDOVIColorMetadata * dm
Private fields internal to dovi_rpu.c.
Definition: dovi_rpu.h:77
DOVIContext::enable
int enable
Definition: dovi_rpu.h:40
DOVIContext::rpu_buf
uint8_t * rpu_buf
temporary buffer
Definition: dovi_rpu.h:79
AVDOVIColorMetadata
Dolby Vision RPU colorspace metadata parameters.
Definition: dovi_meta.h:162
DOVIContext::logctx
void * logctx
Definition: dovi_rpu.h:33
DOVIContext::num_ext_blocks
int num_ext_blocks
Definition: dovi_rpu.h:72
ff_dovi_guess_profile_hevc
int ff_dovi_guess_profile_hevc(const AVDOVIRpuDataHeader *hdr)
Internal helper function to guess the correct DV profile for HEVC.
Definition: dovi_rpu.c:71
AVDOVIDataMapping
Dolby Vision RPU data mapping parameters.
Definition: dovi_meta.h:143
AVDOVIDecoderConfigurationRecord
Definition: dovi_meta.h:54
ff_dovi_ctx_unref
void ff_dovi_ctx_unref(DOVIContext *s)
Completely reset a DOVIContext, preserving only logctx.
Definition: dovi_rpu.c:29