1 /*
2 * MXF SMPTE-436M VBI/ANC parsing functions
3 * Copyright (c) 2025 Jacob Lifshay
4 *
5 * This file is part of FFmpeg.
6 *
7 * FFmpeg is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * FFmpeg is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with FFmpeg; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 */
21
22 #ifndef AVCODEC_SMPTE_436M_H
23 #define AVCODEC_SMPTE_436M_H
24
25 #include <stdint.h>
26
27 /**
28 * Iterator over the ANC packets in a single AV_CODEC_ID_SMPTE_436M_ANC AVPacket's data
29 */
35
36 /**
37 * Wrapping Type from Table 7 (page 13) of:
38 * https://pub.smpte.org/latest/st436/s436m-2006.pdf
39 */
41 {
50 /** not a real wrapping type, just here to guarantee the enum is big enough */
53
54 /**
55 * Payload Sample Coding from Table 4 (page 10) and Table 7 (page 13) of:
56 * https://pub.smpte.org/latest/st436/s436m-2006.pdf
57 */
59 {
60 /** only used for VBI */
62 /** only used for VBI */
64 /** only used for VBI */
66 /** used for VBI and ANC */
68 /** used for VBI and ANC */
70 /** used for VBI and ANC */
72 /** used for VBI and ANC */
74 /** used for VBI and ANC */
76 /** used for VBI and ANC */
78 /** only used for ANC */
80 /** only used for ANC */
82 /** only used for ANC */
84 /** not a real sample coding, just here to guarantee the enum is big enough */
87
88 /** the payload capacity of AVSmpte291mAnc8bit (and of AVSmpte291mAnc10bit when that gets added) */
89 #define AV_SMPTE_291M_ANC_PAYLOAD_CAPACITY 0xFF
90
91 /**
92 * An ANC packet with an 8-bit payload.
93 * This can be decoded from AVSmpte436mCodedAnc::payload.
94 *
95 * Note: Some ANC packets need a 10-bit payload, if stored in this struct,
96 * the most-significant 2 bits of each sample are discarded.
97 */
105
106 /** max number of samples that can be stored in the payload of AVSmpte436mCodedAnc */
107 #define AV_SMPTE_436M_CODED_ANC_SAMPLE_CAPACITY \
108 (AV_SMPTE_291M_ANC_PAYLOAD_CAPACITY + 4) /* 4 for did, sdid_or_dbn, data_count, and checksum */
109 /** max number of bytes that can be stored in the payload of AVSmpte436mCodedAnc */
110 #define AV_SMPTE_436M_CODED_ANC_PAYLOAD_CAPACITY (((AV_SMPTE_436M_CODED_ANC_SAMPLE_CAPACITY + 2) / 3) * 4)
111
112 /**
113 * An encoded ANC packet within a single AV_CODEC_ID_SMPTE_436M_ANC AVPacket's data.
114 * The repeated section of Table 7 (page 13) of:
115 * https://pub.smpte.org/latest/st436/s436m-2006.pdf
116 */
123 /** the payload, has size payload_array_length.
124 * can be decoded into AVSmpte291mAnc8bit
125 */
128
129 /**
130 * Validate a AVSmpte436mCodedAnc structure. Doesn't check if the payload is valid.
131 * @param[in] anc ANC packet to validate
132 * @return 0 on success, AVERROR codes otherwise.
133 */
135
136 /**
137 * Encode ANC packets into a single AV_CODEC_ID_SMPTE_436M_ANC AVPacket's data.
138 * @param[in] anc_packet_count number of ANC packets to encode
139 * @param[in] anc_packets the ANC packets to encode
140 * @param[in] size the size of out. ignored if out is NULL.
141 * @param[out] out Output bytes. Doesn't write anything if out is NULL.
142 * @return the number of bytes written on success, AVERROR codes otherwise.
143 * If out is NULL, returns the number of bytes it would have written.
144 */
146
148
149 /**
150 * Append more ANC packets to a single AV_CODEC_ID_SMPTE_436M_ANC AVPacket's data.
151 * @param[in] anc_packet_count number of ANC packets to encode
152 * @param[in] anc_packets the ANC packets to encode
153 * @param pkt the AVPacket to append to.
154 * it must either be size 0 or contain valid SMPTE_436M_ANC data.
155 * @return 0 on success, AVERROR codes otherwise.
156 */
158
159 /**
160 * Set up iteration over the ANC packets in a single AV_CODEC_ID_SMPTE_436M_ANC AVPacket's data.
161 * @param[in] buf Pointer to the data from a AV_CODEC_ID_SMPTE_436M_ANC AVPacket.
162 * @param[in] buf_size Size of the data from a AV_CODEC_ID_SMPTE_436M_ANC AVPacket.
163 * @param[out] iter Pointer to the iterator.
164 * @return 0 on success, AVERROR codes otherwise.
165 */
167
168 /**
169 * Get the next ANC packet from the iterator, advancing the iterator.
170 * @param[in,out] iter Pointer to the iterator.
171 * @param[out] anc The returned ANC packet.
172 * @return 0 on success, AVERROR_EOF when the iterator has reached the end, AVERROR codes otherwise.
173 */
175
176 /**
177 * Get the minimum number of bytes needed to store a AVSmpte436mCodedAnc payload.
178 * @param sample_coding the payload sample coding
179 * @param sample_count the number of samples stored in the payload
180 * @return returns the minimum number of bytes needed, on error returns < 0.
181 * always <= SMPTE_436M_CODED_ANC_PAYLOAD_CAPACITY
182 */
184
185 /**
186 * Decode a AVSmpte436mCodedAnc payload into AVSmpte291mAnc8bit
187 * @param[in] sample_coding the payload sample coding
188 * @param[in] sample_count the number of samples stored in the payload
189 * @param[in] payload the bytes storing the payload,
190 * the needed size can be obtained from
191 avpriv_smpte_436m_coded_anc_payload_size
192 * @param[in] log_ctx context pointer for av_log
193 * @param[out] out The decoded ANC packet.
194 * @return returns 0 on success, otherwise < 0.
195 */
198 uint16_t sample_count,
199 const uint8_t *payload,
200 void *log_ctx);
201
202 /**
203 * Fill in the correct checksum for a AVSmpte291mAnc8bit
204 * @param[in,out] anc The ANC packet.
205 */
207
208 /**
209 * Compute the sample count needed to encode a AVSmpte291mAnc8bit into a AVSmpte436mCodedAnc payload
210 * @param[in] anc The ANC packet.
211 * @param[in] sample_coding The sample coding.
212 * @param[in] log_ctx context pointer for av_log
213 * @return returns the sample count on success, otherwise < 0.
214 */
217 void *log_ctx);
218
219 /**
220 * Encode a AVSmpte291mAnc8bit into a AVSmpte436mCodedAnc
221 * @param[in] line_number the line number the ANC packet is on
222 * @param[in] wrapping_type the wrapping type
223 * @param[in] sample_coding the payload sample coding
224 * @param[in] payload the ANC packet to encode.
225 * @param[in] log_ctx context pointer for av_log
226 * @param[out] out The encoded ANC packet.
227 * @return returns 0 on success, otherwise < 0.
228 */
230 uint16_t line_number,
234 void *log_ctx);
235
236 /** AVSmpte291mAnc8bit::did when carrying CTA-708 data (for AV_CODEC_ID_EIA_608) */
237 #define AV_SMPTE_291M_ANC_DID_CTA_708 0x61
238
239 /** AVSmpte291mAnc8bit::sdid_or_dbn when carrying CTA-708 data (for AV_CODEC_ID_EIA_608) */
240 #define AV_SMPTE_291M_ANC_SDID_CTA_708 0x1
241
242 /**
243 * Try to decode an ANC packet into EIA-608/CTA-708 data (AV_CODEC_ID_EIA_608). This
244 * @param[in] anc The ANC packet.
245 * @param[in] log_ctx Context pointer for av_log
246 * @param[out] cc_data the buffer to store the extracted EIA-608/CTA-708 data,
247 * you can pass NULL to not store the data.
248 * the required size is 3 * cc_count bytes.
249 * SMPTE_291M_ANC_PAYLOAD_CAPACITY is always enough size.
250 * @return returns cc_count (>= 0) on success, AVERROR(EAGAIN) if it wasn't a CTA-708 ANC packet, < 0 on error.
251 */
253
254 #endif /* AVCODEC_SMPTE_436M_H */