FFmpeg
Functions | Variables
hwcontext.c File Reference
#include "config.h"
#include "avassert.h"
#include "buffer.h"
#include "common.h"
#include "hwcontext.h"
#include "hwcontext_internal.h"
#include "imgutils.h"
#include "log.h"
#include "mem.h"
#include "pixdesc.h"
#include "pixfmt.h"

Go to the source code of this file.

Functions

enum AVHWDeviceType av_hwdevice_find_type_by_name (const char *name)
 Look up an AVHWDeviceType by name. More...
 
const char * av_hwdevice_get_type_name (enum AVHWDeviceType type)
 Get the string name of an AVHWDeviceType. More...
 
enum AVHWDeviceType av_hwdevice_iterate_types (enum AVHWDeviceType prev)
 Iterate over supported device types. More...
 
static void hwdevice_ctx_free (void *opaque, uint8_t *data)
 
AVBufferRefav_hwdevice_ctx_alloc (enum AVHWDeviceType type)
 Allocate an AVHWDeviceContext for a given hardware type. More...
 
int av_hwdevice_ctx_init (AVBufferRef *ref)
 Finalize the device context before use. More...
 
static void hwframe_ctx_free (void *opaque, uint8_t *data)
 
AVBufferRefav_hwframe_ctx_alloc (AVBufferRef *device_ref_in)
 Allocate an AVHWFramesContext tied to a given device context. More...
 
static int hwframe_pool_prealloc (AVBufferRef *ref)
 
int av_hwframe_ctx_init (AVBufferRef *ref)
 Finalize the context before use. More...
 
int av_hwframe_transfer_get_formats (AVBufferRef *hwframe_ref, enum AVHWFrameTransferDirection dir, enum AVPixelFormat **formats, int flags)
 Get a list of possible source or target formats usable in av_hwframe_transfer_data(). More...
 
static int transfer_data_alloc (AVFrame *dst, const AVFrame *src, int flags)
 
int av_hwframe_transfer_data (AVFrame *dst, const AVFrame *src, int flags)
 Copy data to or from a hw surface. More...
 
int av_hwframe_get_buffer (AVBufferRef *hwframe_ref, AVFrame *frame, int flags)
 Allocate a new frame attached to the given AVHWFramesContext. More...
 
void * av_hwdevice_hwconfig_alloc (AVBufferRef *ref)
 Allocate a HW-specific configuration structure for a given HW device. More...
 
AVHWFramesConstraintsav_hwdevice_get_hwframe_constraints (AVBufferRef *ref, const void *hwconfig)
 Get the constraints on HW frames given a device and the HW-specific configuration to be used with that device. More...
 
void av_hwframe_constraints_free (AVHWFramesConstraints **constraints)
 Free an AVHWFrameConstraints structure. More...
 
int av_hwdevice_ctx_create (AVBufferRef **pdevice_ref, enum AVHWDeviceType type, const char *device, AVDictionary *opts, int flags)
 Open a device of the specified type and create an AVHWDeviceContext for it. More...
 
int av_hwdevice_ctx_create_derived_opts (AVBufferRef **dst_ref_ptr, enum AVHWDeviceType type, AVBufferRef *src_ref, AVDictionary *options, int flags)
 Create a new device of the specified type from an existing device. More...
 
int av_hwdevice_ctx_create_derived (AVBufferRef **dst_ref_ptr, enum AVHWDeviceType type, AVBufferRef *src_ref, int flags)
 Create a new device of the specified type from an existing device. More...
 
static void ff_hwframe_unmap (void *opaque, uint8_t *data)
 
int ff_hwframe_map_create (AVBufferRef *hwframe_ref, AVFrame *dst, const AVFrame *src, void(*unmap)(AVHWFramesContext *ctx, HWMapDescriptor *hwmap), void *priv)
 
int av_hwframe_map (AVFrame *dst, const AVFrame *src, int flags)
 Map a hardware frame. More...
 
int av_hwframe_ctx_create_derived (AVBufferRef **derived_frame_ctx, enum AVPixelFormat format, AVBufferRef *derived_device_ctx, AVBufferRef *source_frame_ctx, int flags)
 Create and initialise an AVHWFramesContext as a mapping of another existing AVHWFramesContext on a different device. More...
 
int ff_hwframe_map_replace (AVFrame *dst, const AVFrame *src)
 Replace the current hwmap of dst with the one from src, used for indirect mappings like VAAPI->(DRM)->OpenCL/Vulkan where a direct interop is missing. More...
 

Variables

static const HWContextType *const hw_table []
 
static const char *const hw_type_names []
 
static const AVClass hwdevice_ctx_class
 
static const AVClass hwframe_ctx_class
 

Function Documentation

◆ av_hwdevice_find_type_by_name()

enum AVHWDeviceType av_hwdevice_find_type_by_name ( const char *  name)

Look up an AVHWDeviceType by name.

Parameters
nameString name of the device type (case-insensitive).
Returns
The type from enum AVHWDeviceType, or AV_HWDEVICE_TYPE_NONE if not found.
Examples
hw_decode.c.

Definition at line 83 of file hwcontext.c.

Referenced by hw_device_init_from_string(), hwmap_config_output(), hwupload_query_formats(), ist_add(), main(), qsv_device_create(), and test_device_type().

◆ av_hwdevice_get_type_name()

const char* av_hwdevice_get_type_name ( enum AVHWDeviceType  type)

Get the string name of an AVHWDeviceType.

Parameters
typeType from enum AVHWDeviceType.
Returns
Pointer to a static string containing the name, or NULL if the type is not valid.
Examples
hw_decode.c.

Definition at line 93 of file hwcontext.c.

Referenced by amf_init_context(), choose_decoder(), ff_decode_get_hw_frames_ctx(), hw_device_default_name(), hw_device_for_filter(), hw_device_setup_for_decode(), hw_device_setup_for_encode(), ist_add(), main(), opt_init_hw_device(), print_codec(), show_hwaccels(), test_derivation(), and test_device_type().

◆ av_hwdevice_iterate_types()

enum AVHWDeviceType av_hwdevice_iterate_types ( enum AVHWDeviceType  prev)

Iterate over supported device types.

Parameters
prevAV_HWDEVICE_TYPE_NONE initially, then the previous type returned by this function in subsequent iterations.
Returns
The next usable device type from enum AVHWDeviceType, or AV_HWDEVICE_TYPE_NONE if there are no more.
Examples
hw_decode.c.

Definition at line 102 of file hwcontext.c.

Referenced by ist_add(), main(), opt_init_hw_device(), show_hwaccels(), and test_derivation().

◆ hwdevice_ctx_free()

static void hwdevice_ctx_free ( void *  opaque,
uint8_t *  data 
)
static

Definition at line 123 of file hwcontext.c.

Referenced by av_hwdevice_ctx_alloc().

◆ av_hwdevice_ctx_alloc()

AVBufferRef* av_hwdevice_ctx_alloc ( enum AVHWDeviceType  type)

Allocate an AVHWDeviceContext for a given hardware type.

Parameters
typethe type of the hardware device to allocate.
Returns
a reference to the newly created AVHWDeviceContext on success or NULL on failure.

Definition at line 143 of file hwcontext.c.

Referenced by av_hwdevice_ctx_create(), av_hwdevice_ctx_create_derived_opts(), qsv_init_child_ctx(), and rkmpp_init_decoder().

◆ av_hwdevice_ctx_init()

int av_hwdevice_ctx_init ( AVBufferRef ref)

Finalize the device context before use.

This function must be called after the context is filled with all the required information and before it is used in any way.

Parameters
refa reference to the AVHWDeviceContext
Returns
0 on success, a negative AVERROR code on failure

Definition at line 201 of file hwcontext.c.

Referenced by av_hwdevice_ctx_create(), av_hwdevice_ctx_create_derived_opts(), qsv_init_child_ctx(), and rkmpp_init_decoder().

◆ hwframe_ctx_free()

static void hwframe_ctx_free ( void *  opaque,
uint8_t *  data 
)
static

Definition at line 225 of file hwcontext.c.

Referenced by av_hwframe_ctx_alloc().

◆ av_hwframe_ctx_alloc()

AVBufferRef* av_hwframe_ctx_alloc ( AVBufferRef device_ctx)

◆ hwframe_pool_prealloc()

static int hwframe_pool_prealloc ( AVBufferRef ref)
static

Definition at line 306 of file hwcontext.c.

Referenced by av_hwframe_ctx_init().

◆ av_hwframe_ctx_init()

int av_hwframe_ctx_init ( AVBufferRef ref)

◆ av_hwframe_transfer_get_formats()

int av_hwframe_transfer_get_formats ( AVBufferRef hwframe_ctx,
enum AVHWFrameTransferDirection  dir,
enum AVPixelFormat **  formats,
int  flags 
)

Get a list of possible source or target formats usable in av_hwframe_transfer_data().

Parameters
hwframe_ctxthe frame context to obtain the information for
dirthe direction of the transfer
formatsthe pointer to the output format list will be written here. The list is terminated with AV_PIX_FMT_NONE and must be freed by the caller when no longer needed using av_free(). If this function returns successfully, the format list will have at least one item (not counting the terminator). On failure, the contents of this pointer are unspecified.
flagscurrently unused, should be set to zero
Returns
0 on success, a negative AVERROR code on failure.

Definition at line 386 of file hwcontext.c.

Referenced by hwdownload_config_output(), and transfer_data_alloc().

◆ transfer_data_alloc()

static int transfer_data_alloc ( AVFrame dst,
const AVFrame src,
int  flags 
)
static

Definition at line 398 of file hwcontext.c.

Referenced by av_hwframe_transfer_data().

◆ av_hwframe_transfer_data()

int av_hwframe_transfer_data ( AVFrame dst,
const AVFrame src,
int  flags 
)

Copy data to or from a hw surface.

At least one of dst/src must have an AVHWFramesContext attached.

If src has an AVHWFramesContext attached, then the format of dst (if set) must use one of the formats returned by av_hwframe_transfer_get_formats(src, AV_HWFRAME_TRANSFER_DIRECTION_FROM). If dst has an AVHWFramesContext attached, then the format of src must use one of the formats returned by av_hwframe_transfer_get_formats(dst, AV_HWFRAME_TRANSFER_DIRECTION_TO)

dst may be "clean" (i.e. with data/buf pointers unset), in which case the data buffers will be allocated by this function using av_frame_get_buffer(). If dst->format is set, then this format will be used, otherwise (when dst->format is AV_PIX_FMT_NONE) the first acceptable format will be chosen.

The two frames must have matching allocated dimensions (i.e. equal to AVHWFramesContext.width/height), since not all device types support transferring a sub-rectangle of the whole surface. The display dimensions (i.e. AVFrame.width/height) may be smaller than the allocated dimensions, but also have to be equal for both frames. When the display dimensions are smaller than the allocated dimensions, the content of the padding in the destination frame is unspecified.

Parameters
dstthe destination frame. dst is not touched on failure.
srcthe source frame.
flagscurrently unused, should be set to zero
Returns
0 on success, a negative AVERROR error code on failure.
Examples
hw_decode.c, qsv_decode.c, and vaapi_encode.c.

Definition at line 448 of file hwcontext.c.

Referenced by conv_cuda_convert(), cudaupload_filter_frame(), cuvid_output_frame(), decode_packet(), decode_write(), frame_copy_video(), hwaccel_retrieve_data(), hwdownload_filter_frame(), hwupload_filter_frame(), main(), qsv_transfer_data_child(), and transfer_data_alloc().

◆ av_hwframe_get_buffer()

int av_hwframe_get_buffer ( AVBufferRef hwframe_ctx,
AVFrame frame,
int  flags 
)

Allocate a new frame attached to the given AVHWFramesContext.

Parameters
hwframe_ctxa reference to an AVHWFramesContext
framean empty (freshly allocated or unreffed) frame to be filled with newly allocated buffers.
flagscurrently unused, should be set to zero
Returns
0 on success, a negative AVERROR code on failure
Examples
vaapi_encode.c.

Definition at line 507 of file hwcontext.c.

Referenced by av_frame_make_writable(), av_hwframe_get_buffer(), avcodec_default_get_buffer2(), cuda_bilateral_process(), cudachromakey_process(), cudacolorspace_conv(), cudascale_scale(), cuvid_output_frame(), ff_default_get_video_buffer2(), hwframe_pool_prealloc(), init_hwframe_ctx(), init_stage(), main(), nppscale_scale(), nppsharpen_config(), nppsharpen_filter_frame(), npptranspose_filter(), query_frame(), vaapi_encode_issue(), and vk_get_dpb_pool().

◆ av_hwdevice_hwconfig_alloc()

void* av_hwdevice_hwconfig_alloc ( AVBufferRef device_ctx)

Allocate a HW-specific configuration structure for a given HW device.

After use, the user must free all members as required by the specific hardware structure being used, then free the structure itself with av_free().

Parameters
device_ctxa reference to the associated AVHWDeviceContext.
Returns
The newly created HW-specific configuration structure on success or NULL on failure.

Definition at line 570 of file hwcontext.c.

Referenced by ff_vaapi_vpp_config_output(), vaapi_decode_make_config(), and vaapi_encode_create_recon_frames().

◆ av_hwdevice_get_hwframe_constraints()

AVHWFramesConstraints* av_hwdevice_get_hwframe_constraints ( AVBufferRef ref,
const void *  hwconfig 
)

Get the constraints on HW frames given a device and the HW-specific configuration to be used with that device.

If no HW-specific configuration is provided, returns the maximum possible capabilities of the device.

Parameters
refa reference to the associated AVHWDeviceContext.
hwconfiga filled HW-specific configuration structure, or NULL to return the maximum possible capabilities of the device.
Returns
AVHWFramesConstraints structure describing the constraints on the device, or NULL if not available.

Definition at line 581 of file hwcontext.c.

Referenced by ff_vaapi_vpp_config_output(), hwupload_query_formats(), vaapi_decode_make_config(), and vaapi_encode_create_recon_frames().

◆ av_hwframe_constraints_free()

void av_hwframe_constraints_free ( AVHWFramesConstraints **  constraints)

Free an AVHWFrameConstraints structure.

Parameters
constraintsThe (filled or unfilled) AVHWFrameConstraints structure.

Definition at line 606 of file hwcontext.c.

Referenced by av_hwdevice_get_hwframe_constraints(), ff_vaapi_vpp_config_output(), hwupload_query_formats(), vaapi_decode_make_config(), and vaapi_encode_create_recon_frames().

◆ av_hwdevice_ctx_create()

int av_hwdevice_ctx_create ( AVBufferRef **  device_ctx,
enum AVHWDeviceType  type,
const char *  device,
AVDictionary opts,
int  flags 
)

Open a device of the specified type and create an AVHWDeviceContext for it.

This is a convenience function intended to cover the simple cases. Callers who need to fine-tune device creation/management should open the device manually and then wrap it in an AVHWDeviceContext using av_hwdevice_ctx_alloc()/av_hwdevice_ctx_init().

The returned context is already initialized and ready for use, the caller should not call av_hwdevice_ctx_init() on it. The user_opaque/free fields of the created AVHWDeviceContext are set by this function and should not be touched by the caller.

Parameters
device_ctxOn success, a reference to the newly-created device context will be written here. The reference is owned by the caller and must be released with av_buffer_unref() when no longer needed. On failure, NULL will be written to this pointer.
typeThe type of the device to create.
deviceA type-specific string identifying the device to open.
optsA dictionary of additional (type-specific) options to use in opening the device. The dictionary remains owned by the caller.
flagscurrently unused
Returns
0 on success, a negative AVERROR code on failure.
Examples
hw_decode.c, qsv_decode.c, qsv_transcode.c, vaapi_encode.c, and vaapi_transcode.c.

Definition at line 615 of file hwcontext.c.

Referenced by cudaupload_init(), cuvid_decode_init(), ddagrab_config_props(), hw_decoder_init(), hw_device_init_from_string(), hw_device_init_from_type(), kmsgrab_read_header(), main(), qsv_device_create(), and test_device().

◆ av_hwdevice_ctx_create_derived_opts()

int av_hwdevice_ctx_create_derived_opts ( AVBufferRef **  dst_ctx,
enum AVHWDeviceType  type,
AVBufferRef src_ctx,
AVDictionary options,
int  flags 
)

Create a new device of the specified type from an existing device.

This function performs the same action as av_hwdevice_ctx_create_derived, however, it is able to set options for the new device to be derived.

Parameters
dst_ctxOn success, a reference to the newly-created AVHWDeviceContext.
typeThe type of the new device to create.
src_ctxA reference to an existing AVHWDeviceContext which will be used to create the new device.
optionsOptions for the new device to create, same format as in av_hwdevice_ctx_create.
flagsCurrently unused; should be set to zero.
Returns
Zero on success, a negative AVERROR code on failure.

Definition at line 651 of file hwcontext.c.

Referenced by av_hwdevice_ctx_create_derived().

◆ av_hwdevice_ctx_create_derived()

int av_hwdevice_ctx_create_derived ( AVBufferRef **  dst_ctx,
enum AVHWDeviceType  type,
AVBufferRef src_ctx,
int  flags 
)

Create a new device of the specified type from an existing device.

If the source device is a device of the target type or was originally derived from such a device (possibly through one or more intermediate devices of other types), then this will return a reference to the existing device of the same type as is requested.

Otherwise, it will attempt to derive a new device from the given source device. If direct derivation to the new type is not implemented, it will attempt the same derivation from each ancestor of the source device in turn looking for an implemented derivation method.

Parameters
dst_ctxOn success, a reference to the newly-created AVHWDeviceContext.
typeThe type of the new device to create.
src_ctxA reference to an existing AVHWDeviceContext which will be used to create the new device.
flagsCurrently unused; should be set to zero.
Returns
Zero on success, a negative AVERROR code on failure.

Definition at line 719 of file hwcontext.c.

Referenced by hw_device_init_from_string(), hwmap_config_output(), hwupload_query_formats(), and test_derivation().

◆ ff_hwframe_unmap()

static void ff_hwframe_unmap ( void *  opaque,
uint8_t *  data 
)
static

Definition at line 727 of file hwcontext.c.

Referenced by ff_hwframe_map_create().

◆ ff_hwframe_map_create()

int ff_hwframe_map_create ( AVBufferRef hwframe_ref,
AVFrame dst,
const AVFrame src,
void(*)(AVHWFramesContext *ctx, HWMapDescriptor *hwmap)  unmap,
void *  priv 
)

◆ av_hwframe_map()

int av_hwframe_map ( AVFrame dst,
const AVFrame src,
int  flags 
)

Map a hardware frame.

This has a number of different possible effects, depending on the format and origin of the src and dst frames. On input, src should be a usable frame with valid buffers and dst should be blank (typically as just created by av_frame_alloc()). src should have an associated hwframe context, and dst may optionally have a format and associated hwframe context.

If src was created by mapping a frame from the hwframe context of dst, then this function undoes the mapping - dst is replaced by a reference to the frame that src was originally mapped from.

If both src and dst have an associated hwframe context, then this function attempts to map the src frame from its hardware context to that of dst and then fill dst with appropriate data to be usable there. This will only be possible if the hwframe contexts and associated devices are compatible - given compatible devices, av_hwframe_ctx_create_derived() can be used to create a hwframe context for dst in which mapping should be possible.

If src has a hwframe context but dst does not, then the src frame is mapped to normal memory and should thereafter be usable as a normal frame. If the format is set on dst, then the mapping will attempt to create dst with that format and fail if it is not possible. If format is unset (is AV_PIX_FMT_NONE) then dst will be mapped with whatever the most appropriate format to use is (probably the sw_format of the src hwframe context).

A return value of AVERROR(ENOSYS) indicates that the mapping is not possible with the given arguments and hwframe setup, while other return values indicate that it failed somehow.

On failure, the destination frame will be left blank, except for the hw_frames_ctx/format fields thay may have been set by the caller - those will be preserved as they were.

Parameters
dstDestination frame, to contain the mapping.
srcSource frame, to be mapped.
flagsSome combination of AV_HWFRAME_MAP_* flags.
Returns
Zero on success, negative AVERROR code on failure.

Definition at line 794 of file hwcontext.c.

Referenced by av_hwframe_get_buffer(), hwmap_filter_frame(), hwmap_get_buffer(), qsv_frame_lock(), and qsv_map_from().

◆ av_hwframe_ctx_create_derived()

int av_hwframe_ctx_create_derived ( AVBufferRef **  derived_frame_ctx,
enum AVPixelFormat  format,
AVBufferRef derived_device_ctx,
AVBufferRef source_frame_ctx,
int  flags 
)

Create and initialise an AVHWFramesContext as a mapping of another existing AVHWFramesContext on a different device.

av_hwframe_ctx_init() should not be called after this.

Parameters
derived_frame_ctxOn success, a reference to the newly created AVHWFramesContext.
formatThe AVPixelFormat for the derived context.
derived_device_ctxA reference to the device to create the new AVHWFramesContext on.
source_frame_ctxA reference to an existing AVHWFramesContext which will be mapped to the derived context.
flagsSome combination of AV_HWFRAME_MAP_* flags, defining the mapping parameters to apply to frames which are allocated in the derived device.
Returns
Zero on success, negative AVERROR code on failure.

Definition at line 873 of file hwcontext.c.

Referenced by hwmap_config_output().

◆ ff_hwframe_map_replace()

int ff_hwframe_map_replace ( AVFrame dst,
const AVFrame src 
)

Replace the current hwmap of dst with the one from src, used for indirect mappings like VAAPI->(DRM)->OpenCL/Vulkan where a direct interop is missing.

Definition at line 949 of file hwcontext.c.

Variable Documentation

◆ hw_table

const HWContextType* const hw_table[]
static

Definition at line 32 of file hwcontext.c.

Referenced by av_hwdevice_ctx_alloc(), and av_hwdevice_iterate_types().

◆ hw_type_names

const char* const hw_type_names[]
static
Initial value:
= {
[AV_HWDEVICE_TYPE_D3D11VA] = "d3d11va",
[AV_HWDEVICE_TYPE_VIDEOTOOLBOX] = "videotoolbox",
[AV_HWDEVICE_TYPE_MEDIACODEC] = "mediacodec",
}

Definition at line 69 of file hwcontext.c.

Referenced by av_hwdevice_find_type_by_name(), and av_hwdevice_get_type_name().

◆ hwdevice_ctx_class

const AVClass hwdevice_ctx_class
static
Initial value:
= {
.class_name = "AVHWDeviceContext",
.item_name = av_default_item_name,
}

Definition at line 117 of file hwcontext.c.

Referenced by av_hwdevice_ctx_alloc().

◆ hwframe_ctx_class

const AVClass hwframe_ctx_class
static
Initial value:
= {
.class_name = "AVHWFramesContext",
.item_name = av_default_item_name,
}

Definition at line 219 of file hwcontext.c.

Referenced by av_hwframe_ctx_alloc().

AV_HWDEVICE_TYPE_MEDIACODEC
@ AV_HWDEVICE_TYPE_MEDIACODEC
Definition: hwcontext.h:38
AV_HWDEVICE_TYPE_VIDEOTOOLBOX
@ AV_HWDEVICE_TYPE_VIDEOTOOLBOX
Definition: hwcontext.h:34
AV_HWDEVICE_TYPE_VULKAN
@ AV_HWDEVICE_TYPE_VULKAN
Definition: hwcontext.h:39
AV_HWDEVICE_TYPE_CUDA
@ AV_HWDEVICE_TYPE_CUDA
Definition: hwcontext.h:30
AV_HWDEVICE_TYPE_D3D11VA
@ AV_HWDEVICE_TYPE_D3D11VA
Definition: hwcontext.h:35
LIBAVUTIL_VERSION_INT
#define LIBAVUTIL_VERSION_INT
Definition: version.h:85
AV_HWDEVICE_TYPE_DXVA2
@ AV_HWDEVICE_TYPE_DXVA2
Definition: hwcontext.h:32
av_default_item_name
const char * av_default_item_name(void *ptr)
Return the context name.
Definition: log.c:237
AV_HWDEVICE_TYPE_OPENCL
@ AV_HWDEVICE_TYPE_OPENCL
Definition: hwcontext.h:37
AV_HWDEVICE_TYPE_VAAPI
@ AV_HWDEVICE_TYPE_VAAPI
Definition: hwcontext.h:31
AV_HWDEVICE_TYPE_VDPAU
@ AV_HWDEVICE_TYPE_VDPAU
Definition: hwcontext.h:29
AV_HWDEVICE_TYPE_QSV
@ AV_HWDEVICE_TYPE_QSV
Definition: hwcontext.h:33
AV_HWDEVICE_TYPE_DRM
@ AV_HWDEVICE_TYPE_DRM
Definition: hwcontext.h:36