1 /*
2 * This file is part of FFmpeg.
3 *
4 * FFmpeg is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * FFmpeg is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with FFmpeg; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17 */
18
19 #ifndef AVUTIL_HWCONTEXT_H
20 #define AVUTIL_HWCONTEXT_H
21
26
42 /* OpenHarmony Codec device */
44 };
45
46 /**
47 * This struct aggregates all the (hardware/vendor-specific) "high-level" state,
48 * i.e. state that is not tied to a concrete processing configuration.
49 * E.g., in an API that supports hardware-accelerated encoding and decoding,
50 * this struct will (if possible) wrap the state that is common to both encoding
51 * and decoding and from which specific instances of encoders or decoders can be
52 * derived.
53 *
54 * This struct is reference-counted with the AVBuffer mechanism. The
55 * av_hwdevice_ctx_alloc() constructor yields a reference, whose data field
56 * points to the actual AVHWDeviceContext. Further objects derived from
57 * AVHWDeviceContext (such as AVHWFramesContext, describing a frame pool with
58 * specific properties) will hold an internal reference to it. After all the
59 * references are released, the AVHWDeviceContext itself will be freed,
60 * optionally invoking a user-specified callback for uninitializing the hardware
61 * state.
62 */
64 /**
65 * A class for logging. Set by av_hwdevice_ctx_alloc().
66 */
68
69 /**
70 * This field identifies the underlying API used for hardware access.
71 *
72 * This field is set when this struct is allocated and never changed
73 * afterwards.
74 */
76
77 /**
78 * The format-specific data, allocated and freed by libavutil along with
79 * this context.
80 *
81 * Should be cast by the user to the format-specific context defined in the
82 * corresponding header (hwcontext_*.h) and filled as described in the
83 * documentation before calling av_hwdevice_ctx_init().
84 *
85 * After calling av_hwdevice_ctx_init() this struct should not be modified
86 * by the caller.
87 */
89
90 /**
91 * This field may be set by the caller before calling av_hwdevice_ctx_init().
92 *
93 * If non-NULL, this callback will be called when the last reference to
94 * this context is unreferenced, immediately before it is freed.
95 *
96 * @note when other objects (e.g an AVHWFramesContext) are derived from this
97 * struct, this callback will be invoked after all such child objects
98 * are fully uninitialized and their respective destructors invoked.
99 */
101
102 /**
103 * Arbitrary user data, to be used e.g. by the free() callback.
104 */
107
108 /**
109 * This struct describes a set or pool of "hardware" frames (i.e. those with
110 * data not located in normal system memory). All the frames in the pool are
111 * assumed to be allocated in the same way and interchangeable.
112 *
113 * This struct is reference-counted with the AVBuffer mechanism and tied to a
114 * given AVHWDeviceContext instance. The av_hwframe_ctx_alloc() constructor
115 * yields a reference, whose data field points to the actual AVHWFramesContext
116 * struct.
117 */
119 /**
120 * A class for logging.
121 */
123
124 /**
125 * A reference to the parent AVHWDeviceContext. This reference is owned and
126 * managed by the enclosing AVHWFramesContext, but the caller may derive
127 * additional references from it.
128 */
130
131 /**
132 * The parent AVHWDeviceContext. This is simply a pointer to
133 * device_ref->data provided for convenience.
134 *
135 * Set by libavutil in av_hwframe_ctx_init().
136 */
138
139 /**
140 * The format-specific data, allocated and freed automatically along with
141 * this context.
142 *
143 * The user shall ignore this field if the corresponding format-specific
144 * header (hwcontext_*.h) does not define a context to be used as
145 * AVHWFramesContext.hwctx.
146 *
147 * Otherwise, it should be cast by the user to said context and filled
148 * as described in the documentation before calling av_hwframe_ctx_init().
149 *
150 * After any frames using this context are created, the contents of this
151 * struct should not be modified by the caller.
152 */
154
155 /**
156 * This field may be set by the caller before calling av_hwframe_ctx_init().
157 *
158 * If non-NULL, this callback will be called when the last reference to
159 * this context is unreferenced, immediately before it is freed.
160 */
162
163 /**
164 * Arbitrary user data, to be used e.g. by the free() callback.
165 */
167
168 /**
169 * A pool from which the frames are allocated by av_hwframe_get_buffer().
170 * This field may be set by the caller before calling av_hwframe_ctx_init().
171 * The buffers returned by calling av_buffer_pool_get() on this pool must
172 * have the properties described in the documentation in the corresponding hw
173 * type's header (hwcontext_*.h). The pool will be freed strictly before
174 * this struct's free() callback is invoked.
175 *
176 * This field may be NULL, then libavutil will attempt to allocate a pool
177 * internally. Note that certain device types enforce pools allocated at
178 * fixed size (frame count), which cannot be extended dynamically. In such a
179 * case, initial_pool_size must be set appropriately.
180 */
182
183 /**
184 * Initial size of the frame pool. If a device type does not support
185 * dynamically resizing the pool, then this is also the maximum pool size.
186 *
187 * May be set by the caller before calling av_hwframe_ctx_init(). Must be
188 * set if pool is NULL and the device type does not support dynamic pools.
189 */
191
192 /**
193 * The pixel format identifying the underlying HW surface type.
194 *
195 * Must be a hwaccel format, i.e. the corresponding descriptor must have the
196 * AV_PIX_FMT_FLAG_HWACCEL flag set.
197 *
198 * Must be set by the user before calling av_hwframe_ctx_init().
199 */
201
202 /**
203 * The pixel format identifying the actual data layout of the hardware
204 * frames.
205 *
206 * Must be set by the caller before calling av_hwframe_ctx_init().
207 *
208 * @note when the underlying API does not provide the exact data layout, but
209 * only the colorspace/bit depth, this field should be set to the fully
210 * planar version of that format (e.g. for 8-bit 420 YUV it should be
211 * AV_PIX_FMT_YUV420P, not AV_PIX_FMT_NV12 or anything else).
212 */
214
215 /**
216 * The allocated dimensions of the frames in this pool.
217 *
218 * Must be set by the user before calling av_hwframe_ctx_init().
219 */
222
223 /**
224 * Look up an AVHWDeviceType by name.
225 *
226 * @param name String name of the device type (case-insensitive).
227 * @return The type from enum AVHWDeviceType, or AV_HWDEVICE_TYPE_NONE if
228 * not found.
229 */
231
232 /** Get the string name of an AVHWDeviceType.
233 *
234 * @param type Type from enum AVHWDeviceType.
235 * @return Pointer to a static string containing the name, or NULL if the type
236 * is not valid.
237 */
239
240 /**
241 * Iterate over supported device types.
242 *
243 * @param prev AV_HWDEVICE_TYPE_NONE initially, then the previous type
244 * returned by this function in subsequent iterations.
245 * @return The next usable device type from enum AVHWDeviceType, or
246 * AV_HWDEVICE_TYPE_NONE if there are no more.
247 */
249
250 /**
251 * Allocate an AVHWDeviceContext for a given hardware type.
252 *
253 * @param type the type of the hardware device to allocate.
254 * @return a reference to the newly created AVHWDeviceContext on success or NULL
255 * on failure.
256 */
258
259 /**
260 * Finalize the device context before use. This function must be called after
261 * the context is filled with all the required information and before it is
262 * used in any way.
263 *
264 * @param ref a reference to the AVHWDeviceContext
265 * @return 0 on success, a negative AVERROR code on failure
266 */
268
269 /**
270 * Open a device of the specified type and create an AVHWDeviceContext for it.
271 *
272 * This is a convenience function intended to cover the simple cases. Callers
273 * who need to fine-tune device creation/management should open the device
274 * manually and then wrap it in an AVHWDeviceContext using
275 * av_hwdevice_ctx_alloc()/av_hwdevice_ctx_init().
276 *
277 * The returned context is already initialized and ready for use, the caller
278 * should not call av_hwdevice_ctx_init() on it. The user_opaque/free fields of
279 * the created AVHWDeviceContext are set by this function and should not be
280 * touched by the caller.
281 *
282 * @param device_ctx On success, a reference to the newly-created device context
283 * will be written here. The reference is owned by the caller
284 * and must be released with av_buffer_unref() when no longer
285 * needed. On failure, NULL will be written to this pointer.
286 * @param type The type of the device to create.
287 * @param device A type-specific string identifying the device to open.
288 * @param opts A dictionary of additional (type-specific) options to use in
289 * opening the device. The dictionary remains owned by the caller.
290 * @param flags currently unused
291 *
292 * @return 0 on success, a negative AVERROR code on failure.
293 */
296
297 /**
298 * Create a new device of the specified type from an existing device.
299 *
300 * If the source device is a device of the target type or was originally
301 * derived from such a device (possibly through one or more intermediate
302 * devices of other types), then this will return a reference to the
303 * existing device of the same type as is requested.
304 *
305 * Otherwise, it will attempt to derive a new device from the given source
306 * device. If direct derivation to the new type is not implemented, it will
307 * attempt the same derivation from each ancestor of the source device in
308 * turn looking for an implemented derivation method.
309 *
310 * @param dst_ctx On success, a reference to the newly-created
311 * AVHWDeviceContext.
312 * @param type The type of the new device to create.
313 * @param src_ctx A reference to an existing AVHWDeviceContext which will be
314 * used to create the new device.
315 * @param flags Currently unused; should be set to zero.
316 * @return Zero on success, a negative AVERROR code on failure.
317 */
321
322 /**
323 * Create a new device of the specified type from an existing device.
324 *
325 * This function performs the same action as av_hwdevice_ctx_create_derived,
326 * however, it is able to set options for the new device to be derived.
327 *
328 * @param dst_ctx On success, a reference to the newly-created
329 * AVHWDeviceContext.
330 * @param type The type of the new device to create.
331 * @param src_ctx A reference to an existing AVHWDeviceContext which will be
332 * used to create the new device.
333 * @param options Options for the new device to create, same format as in
334 * av_hwdevice_ctx_create.
335 * @param flags Currently unused; should be set to zero.
336 * @return Zero on success, a negative AVERROR code on failure.
337 */
342
343 /**
344 * Allocate an AVHWFramesContext tied to a given device context.
345 *
346 * @param device_ctx a reference to a AVHWDeviceContext. This function will make
347 * a new reference for internal use, the one passed to the
348 * function remains owned by the caller.
349 * @return a reference to the newly created AVHWFramesContext on success or NULL
350 * on failure.
351 */
353
354 /**
355 * Finalize the context before use. This function must be called after the
356 * context is filled with all the required information and before it is attached
357 * to any frames.
358 *
359 * @param ref a reference to the AVHWFramesContext
360 * @return 0 on success, a negative AVERROR code on failure
361 */
363
364 /**
365 * Allocate a new frame attached to the given AVHWFramesContext.
366 *
367 * @param hwframe_ctx a reference to an AVHWFramesContext
368 * @param frame an empty (freshly allocated or unreffed) frame to be filled with
369 * newly allocated buffers.
370 * @param flags currently unused, should be set to zero
371 * @return 0 on success, a negative AVERROR code on failure
372 */
374
375 /**
376 * Copy data to or from a hw surface. At least one of dst/src must have an
377 * AVHWFramesContext attached.
378 *
379 * If src has an AVHWFramesContext attached, then the format of dst (if set)
380 * must use one of the formats returned by av_hwframe_transfer_get_formats(src,
381 * AV_HWFRAME_TRANSFER_DIRECTION_FROM).
382 * If dst has an AVHWFramesContext attached, then the format of src must use one
383 * of the formats returned by av_hwframe_transfer_get_formats(dst,
384 * AV_HWFRAME_TRANSFER_DIRECTION_TO)
385 *
386 * dst may be "clean" (i.e. with data/buf pointers unset), in which case the
387 * data buffers will be allocated by this function using av_frame_get_buffer().
388 * If dst->format is set, then this format will be used, otherwise (when
389 * dst->format is AV_PIX_FMT_NONE) the first acceptable format will be chosen.
390 *
391 * The two frames must have matching allocated dimensions (i.e. equal to
392 * AVHWFramesContext.width/height), since not all device types support
393 * transferring a sub-rectangle of the whole surface. The display dimensions
394 * (i.e. AVFrame.width/height) may be smaller than the allocated dimensions, but
395 * also have to be equal for both frames. When the display dimensions are
396 * smaller than the allocated dimensions, the content of the padding in the
397 * destination frame is unspecified.
398 *
399 * @param dst the destination frame. dst is not touched on failure.
400 * @param src the source frame.
401 * @param flags currently unused, should be set to zero
402 * @return 0 on success, a negative AVERROR error code on failure.
403 */
405
407 /**
408 * Transfer the data from the queried hw frame.
409 */
411
412 /**
413 * Transfer the data to the queried hw frame.
414 */
416 };
417
418 /**
419 * Get a list of possible source or target formats usable in
420 * av_hwframe_transfer_data().
421 *
422 * @param hwframe_ctx the frame context to obtain the information for
423 * @param dir the direction of the transfer
424 * @param formats the pointer to the output format list will be written here.
425 * The list is terminated with AV_PIX_FMT_NONE and must be freed
426 * by the caller when no longer needed using av_free().
427 * If this function returns successfully, the format list will
428 * have at least one item (not counting the terminator).
429 * On failure, the contents of this pointer are unspecified.
430 * @param flags currently unused, should be set to zero
431 * @return 0 on success, a negative AVERROR code on failure.
432 */
436
437
438 /**
439 * This struct describes the constraints on hardware frames attached to
440 * a given device with a hardware-specific configuration. This is returned
441 * by av_hwdevice_get_hwframe_constraints() and must be freed by
442 * av_hwframe_constraints_free() after use.
443 */
445 /**
446 * A list of possible values for format in the hw_frames_ctx,
447 * terminated by AV_PIX_FMT_NONE. This member will always be filled.
448 */
450
451 /**
452 * A list of possible values for sw_format in the hw_frames_ctx,
453 * terminated by AV_PIX_FMT_NONE. Can be NULL if this information is
454 * not known.
455 */
457
458 /**
459 * The minimum size of frames in this hw_frames_ctx.
460 * (Zero if not known.)
461 */
464
465 /**
466 * The maximum size of frames in this hw_frames_ctx.
467 * (INT_MAX if not known / no limit.)
468 */
472
473 /**
474 * Allocate a HW-specific configuration structure for a given HW device.
475 * After use, the user must free all members as required by the specific
476 * hardware structure being used, then free the structure itself with
477 * av_free().
478 *
479 * @param device_ctx a reference to the associated AVHWDeviceContext.
480 * @return The newly created HW-specific configuration structure on
481 * success or NULL on failure.
482 */
484
485 /**
486 * Get the constraints on HW frames given a device and the HW-specific
487 * configuration to be used with that device. If no HW-specific
488 * configuration is provided, returns the maximum possible capabilities
489 * of the device.
490 *
491 * @param ref a reference to the associated AVHWDeviceContext.
492 * @param hwconfig a filled HW-specific configuration structure, or NULL
493 * to return the maximum possible capabilities of the device.
494 * @return AVHWFramesConstraints structure describing the constraints
495 * on the device, or NULL if not available.
496 */
498 const void *hwconfig);
499
500 /**
501 * Free an AVHWFrameConstraints structure.
502 *
503 * @param constraints The (filled or unfilled) AVHWFrameConstraints structure.
504 */
506
507
508 /**
509 * Flags to apply to frame mappings.
510 */
511 enum {
512 /**
513 * The mapping must be readable.
514 */
516 /**
517 * The mapping must be writeable.
518 */
520 /**
521 * The mapped frame will be overwritten completely in subsequent
522 * operations, so the current frame data need not be loaded. Any values
523 * which are not overwritten are unspecified.
524 */
526 /**
527 * The mapping must be direct. That is, there must not be any copying in
528 * the map or unmap steps. Note that performance of direct mappings may
529 * be much lower than normal memory.
530 */
532 };
533
534 /**
535 * Map a hardware frame.
536 *
537 * This has a number of different possible effects, depending on the format
538 * and origin of the src and dst frames. On input, src should be a usable
539 * frame with valid buffers and dst should be blank (typically as just created
540 * by av_frame_alloc()). src should have an associated hwframe context, and
541 * dst may optionally have a format and associated hwframe context.
542 *
543 * If src was created by mapping a frame from the hwframe context of dst,
544 * then this function undoes the mapping - dst is replaced by a reference to
545 * the frame that src was originally mapped from.
546 *
547 * If both src and dst have an associated hwframe context, then this function
548 * attempts to map the src frame from its hardware context to that of dst and
549 * then fill dst with appropriate data to be usable there. This will only be
550 * possible if the hwframe contexts and associated devices are compatible -
551 * given compatible devices, av_hwframe_ctx_create_derived() can be used to
552 * create a hwframe context for dst in which mapping should be possible.
553 *
554 * If src has a hwframe context but dst does not, then the src frame is
555 * mapped to normal memory and should thereafter be usable as a normal frame.
556 * If the format is set on dst, then the mapping will attempt to create dst
557 * with that format and fail if it is not possible. If format is unset (is
558 * AV_PIX_FMT_NONE) then dst will be mapped with whatever the most appropriate
559 * format to use is (probably the sw_format of the src hwframe context).
560 *
561 * A return value of AVERROR(ENOSYS) indicates that the mapping is not
562 * possible with the given arguments and hwframe setup, while other return
563 * values indicate that it failed somehow.
564 *
565 * On failure, the destination frame will be left blank, except for the
566 * hw_frames_ctx/format fields they may have been set by the caller - those will
567 * be preserved as they were.
568 *
569 * @param dst Destination frame, to contain the mapping.
570 * @param src Source frame, to be mapped.
571 * @param flags Some combination of AV_HWFRAME_MAP_* flags.
572 * @return Zero on success, negative AVERROR code on failure.
573 */
575
576
577 /**
578 * Create and initialise an AVHWFramesContext as a mapping of another existing
579 * AVHWFramesContext on a different device.
580 *
581 * av_hwframe_ctx_init() should not be called after this.
582 *
583 * @param derived_frame_ctx On success, a reference to the newly created
584 * AVHWFramesContext.
585 * @param format The AVPixelFormat for the derived context.
586 * @param derived_device_ctx A reference to the device to create the new
587 * AVHWFramesContext on.
588 * @param source_frame_ctx A reference to an existing AVHWFramesContext
589 * which will be mapped to the derived context.
590 * @param flags Some combination of AV_HWFRAME_MAP_* flags, defining the
591 * mapping parameters to apply to frames which are allocated
592 * in the derived device.
593 * @return Zero on success, negative AVERROR code on failure.
594 */
600
601 #endif /* AVUTIL_HWCONTEXT_H */