Files | Data Structures | Macros | Functions


file  buffer.h

Data Structures

struct  AVBufferRef
 A reference to a data buffer. More...


#define AV_BUFFER_FLAG_READONLY   (1 << 0)
 Always treat the buffer as read-only, even when it has only one reference. More...


AVBufferRefav_buffer_alloc (size_t size)
 Allocate an AVBuffer of the given size using av_malloc(). More...
AVBufferRefav_buffer_allocz (size_t size)
 Same as av_buffer_alloc(), except the returned buffer will be initialized to zero. More...
AVBufferRefav_buffer_create (uint8_t *data, size_t size, void(*free)(void *opaque, uint8_t *data), void *opaque, int flags)
 Create an AVBuffer from an existing array. More...
void av_buffer_default_free (void *opaque, uint8_t *data)
 Default free callback, which calls av_free() on the buffer data. More...
AVBufferRefav_buffer_ref (const AVBufferRef *buf)
 Create a new reference to an AVBuffer. More...
void av_buffer_unref (AVBufferRef **buf)
 Free a given reference and automatically free the buffer if there are no more references to it. More...
int av_buffer_is_writable (const AVBufferRef *buf)
void * av_buffer_get_opaque (const AVBufferRef *buf)
int av_buffer_get_ref_count (const AVBufferRef *buf)
int av_buffer_make_writable (AVBufferRef **buf)
 Create a writable reference from a given buffer reference, avoiding data copy if possible. More...
int av_buffer_realloc (AVBufferRef **buf, size_t size)
 Reallocate a given buffer. More...
int av_buffer_replace (AVBufferRef **dst, const AVBufferRef *src)
 Ensure dst refers to the same data as src. More...

Detailed Description

AVBuffer is an API for reference-counted data buffers.

There are two core objects in this API – AVBuffer and AVBufferRef. AVBuffer represents the data buffer itself; it is opaque and not meant to be accessed by the caller directly, but only through AVBufferRef. However, the caller may e.g. compare two AVBuffer pointers to check whether two different references are describing the same data buffer. AVBufferRef represents a single reference to an AVBuffer and it is the object that may be manipulated by the caller directly.

There are two functions provided for creating a new AVBuffer with a single reference – av_buffer_alloc() to just allocate a new buffer, and av_buffer_create() to wrap an existing array in an AVBuffer. From an existing reference, additional references may be created with av_buffer_ref(). Use av_buffer_unref() to free a reference (this will automatically free the data once all the references are freed).

The convention throughout this API and the rest of FFmpeg is such that the buffer is considered writable if there exists only one reference to it (and it has not been marked as read-only). The av_buffer_is_writable() function is provided to check whether this is true and av_buffer_make_writable() will automatically create a new writable buffer when necessary. Of course nothing prevents the calling code from violating this convention, however that is safe only when all the existing references are under its control.

Referencing and unreferencing the buffers is thread-safe and thus may be done from multiple threads simultaneously without any need for additional locking.
Two different references to the same buffer can point to different parts of the buffer (i.e. their AVBufferRef.data will not be equal).

Macro Definition Documentation


#define AV_BUFFER_FLAG_READONLY   (1 << 0)

Always treat the buffer as read-only, even when it has only one reference.

Definition at line 114 of file buffer.h.

Function Documentation

◆ av_buffer_alloc()

AVBufferRef* av_buffer_alloc ( size_t  size)

◆ av_buffer_allocz()

AVBufferRef* av_buffer_allocz ( size_t  size)

◆ av_buffer_create()

AVBufferRef* av_buffer_create ( uint8_t *  data,
size_t  size,
void(*)(void *opaque, uint8_t *data free,
void *  opaque,
int  flags 

Create an AVBuffer from an existing array.

If this function is successful, data is owned by the AVBuffer. The caller may only access data through the returned AVBufferRef and references derived from it. If this function fails, data is left untouched.

datadata array
sizesize of data in bytes
freea callback for freeing this buffer's data
opaqueparameter to be got for processing or passed to free
flagsa combination of AV_BUFFER_FLAG_*
an AVBufferRef referring to data on success, NULL on failure.

Definition at line 55 of file buffer.c.

Referenced by alloc_data_buf(), alloc_rbsp_buffer(), av_buffer_alloc(), av_buffer_realloc(), av_detection_bbox_create_side_data(), av_hwdevice_ctx_alloc(), av_hwframe_ctx_alloc(), av_packet_from_data(), av_video_enc_params_create_side_data(), av_video_hint_create_side_data(), bufref_wrap_interface(), cbs_h2645_assemble_fragment(), cbs_insert_unit_data(), cuda_pool_alloc(), d3d12va_pool_alloc(), dxva2_pool_alloc(), ff_attach_decode_data(), ff_decode_content_light_new_ext(), ff_decode_mastering_display_new_ext(), ff_dovi_attach_side_data(), ff_flac_parse_picture(), ff_hwframe_map_create(), ff_videotoolbox_alloc_frame(), ff_vk_create_avbuf(), ff_vk_create_imageviews(), ff_vk_decode_create_params(), ffmmal_set_ref(), fg_send_command(), frame_data_ensure(), h2645_sei_to_side_data(), kmsgrab_read_packet(), lavfi_read_packet(), mediacodec_wrap_hw_buffer(), mmap_read_frame(), nvdec_alloc_dummy(), opencl_pool_alloc(), qsv_dynamic_pool_alloc(), qsv_fixed_pool_alloc(), read_header_vs(), read_packet_vs(), rkmpp_retrieve_frame(), subtitle_wrap_frame(), v4l2_buf_to_bufref(), vaapi_pool_alloc(), vdpau_pool_alloc(), decklink_input_callback::VideoInputFrameArrived(), vt_pool_alloc_buffer(), vulkan_pool_alloc(), wrap_texture_buf(), wrapped_avframe_encode(), write_uncoded_frame_internal(), and xcbgrab_frame().

◆ av_buffer_default_free()

void av_buffer_default_free ( void *  opaque,
uint8_t *  data 

Default free callback, which calls av_free() on the buffer data.

This function is meant to be passed to av_buffer_create(), not called directly.

Definition at line 72 of file buffer.c.

Referenced by av_buffer_alloc(), av_buffer_realloc(), av_packet_from_data(), buffer_create(), and ff_flac_parse_picture().

◆ av_buffer_ref()

AVBufferRef* av_buffer_ref ( const AVBufferRef buf)

Create a new reference to an AVBuffer.

a new AVBufferRef referring to the same AVBuffer as buf or NULL on failure.

Definition at line 103 of file buffer.c.

Referenced by amf_init_context(), av1_receive_frame_internal(), av_buffer_replace(), av_buffersrc_parameters_set(), av_frame_ref(), av_frame_side_data_clone(), av_hwdevice_ctx_create_derived_opts(), av_hwframe_ctx_alloc(), av_hwframe_ctx_create_derived(), av_hwframe_get_buffer(), av_packet_ref(), av_write_frame(), bitpacked_decode_uyvy422(), bwdif_vulkan_config_output(), cbs_av1_ref_tile_data(), cbs_av1_write_obu(), cbs_clone_noncomplex_unit_content(), cbs_h264_read_nal_unit(), cbs_h265_read_nal_unit(), cbs_h266_read_nal_unit(), cbs_insert_unit_data(), cbs_jpeg_read_unit(), cbs_mpeg2_read_unit(), cbs_read_data(), cbs_vp8_read_unit(), cbs_vp9_assemble_fragment(), cbs_vp9_read_unit(), config_input(), config_output(), config_props(), config_props_output(), config_props_ref(), cudaupload_config_output(), cuvid_decode_init(), cuvid_output_frame(), ddagrab_config_props(), dec_enc(), ff_cbs_write_packet(), ff_filter_config_links(), ff_h2645_sei_ctx_replace(), ff_hwframe_map_create(), ff_nvdec_decode_init(), ff_vaapi_encode_init(), ff_vaapi_vpp_config_input(), ff_vaapi_vpp_config_output(), ff_vk_decode_init(), ff_vk_exec_add_dep_buf(), ff_vk_filter_config_output(), ff_vk_filter_init_context(), ffmmal_add_packet(), frame_add_buf(), frame_copy_props(), frame_data_submit(), frame_header_obu(), graph_parse(), hw_decoder_init(), hw_device_setup_for_decode(), hw_device_setup_for_encode(), hwdownload_config_input(), hwmap_config_output(), hwmap_filter_frame(), hwupload_config_output(), hwupload_query_formats(), init_processing_chain(), kmsgrab_read_packet(), libdav1d_receive_frame(), LLVMFuzzerTestOneInput(), main(), mpeg4_unpack_bframes_filter(), nppsharpen_config(), npptranspose_config_props(), nvdec_decoder_create(), nvenc_store_frame_data(), open_input_file(), opencl_filter_set_device(), overlay_cuda_config_output(), parse_packet(), qsv_create_mids(), qsv_frame_lock(), qsv_init_session(), qsv_map_from(), qsv_setup_mids(), qsvenc_init_session(), raw_decode(), read_packet_vs(), rkmpp_retrieve_frame(), set_hwframe_ctx(), set_side_data(), testsrc_vulkan_config_props(), transpose_opencl_config_output(), transpose_vaapi_vpp_config_output(), transpose_vt_config_output(), try_push_frame(), update_context_from_thread(), videotoolbox_postproc_frame(), and vpx_decode().

◆ av_buffer_unref()

void av_buffer_unref ( AVBufferRef **  buf)

Free a given reference and automatically free the buffer if there are no more references to it.

bufthe reference to be freed. The pointer is set to NULL on return.

Definition at line 139 of file buffer.c.

Referenced by addroi_filter_frame(), alloc_rbsp_buffer(), asf_parse_packet(), av1_decode_flush(), av1_decode_free(), av1_receive_frame_internal(), av_buffer_replace(), av_buffersrc_parameters_set(), av_detection_bbox_create_side_data(), av_frame_new_side_data(), av_frame_replace(), av_frame_side_data_clone(), av_frame_side_data_new(), av_frame_unref(), av_hwdevice_ctx_create(), av_hwdevice_ctx_create_derived_opts(), av_hwframe_ctx_alloc(), av_hwframe_ctx_create_derived(), av_hwframe_get_buffer(), av_packet_copy_props(), av_packet_make_writable(), av_packet_unref(), av_video_enc_params_create_side_data(), av_video_hint_create_side_data(), avcodec_get_hw_frames_parameters(), avfilter_free(), avi_read_close(), bitpacked_decode_uyvy422(), bwdif_vulkan_config_output(), cbs_av1_close(), cbs_av1_flush(), cbs_av1_free_metadata(), cbs_av1_write_obu(), cbs_default_free_unit_content(), cbs_insert_unit_data(), cbs_unit_uninit(), cbs_vp9_assemble_fragment(), cudabilateral_uninit(), cudachromakey_uninit(), cudacolorspace_uninit(), cudascale_uninit(), cudaupload_config_output(), cudaupload_uninit(), cuvid_decode_end(), ddagrab_uninit(), decode_nal_units(), decode_receive_frame_internal(), deint_cuda_uninit(), drawbox_vaapi_uninit(), evc_frame_merge_filter(), export_metadata(), extract_extradata_av1(), extract_extradata_h2645(), ff_amf_encode_close(), ff_attach_decode_data(), ff_cbs_fragment_reset(), ff_cbs_write_fragment_data(), ff_cbs_write_packet(), ff_codec_close(), ff_d3d12va_decode_uninit(), ff_decode_content_light_new_ext(), ff_decode_get_hw_frames_ctx(), ff_decode_mastering_display_new_ext(), ff_dovi_attach_side_data(), ff_dxva2_decode_uninit(), ff_flac_parse_picture(), ff_frame_new_side_data_from_buf_ext(), ff_frame_thread_free(), ff_h2645_packet_uninit(), ff_h2645_sei_ctx_replace(), ff_h2645_sei_reset(), ff_h2645_sei_to_frame(), ff_hwaccel_uninit(), ff_hwframe_map_create(), ff_hwframe_unmap(), ff_icc_profile_attach(), ff_nvdec_decode_init(), ff_nvenc_encode_close(), ff_opencl_filter_config_output(), ff_opencl_filter_uninit(), ff_qsv_close_internal_session(), ff_qsv_enc_close(), ff_vaapi_encode_close(), ff_vaapi_vpp_config_output(), ff_vaapi_vpp_ctx_uninit(), ff_vaapi_vpp_pipeline_uninit(), ff_vk_create_imageviews(), ff_vk_decode_add_slice(), ff_vk_decode_free_frame(), ff_vk_decode_uninit(), ff_vk_exec_discard_deps(), ff_vk_filter_config_output(), ff_vk_filter_init_context(), ff_vk_get_pooled_buffer(), ff_vk_params_invalidate(), ff_vk_uninit(), ff_vk_video_get_buffer(), ffmmal_fill_input_port(), ffmmal_stop_decoder(), fg_free(), fg_send_command(), flashsv_encode_end(), flush(), frame_copy_props(), frame_data_ensure(), frame_data_free(), frame_data_uninit(), frame_header_obu(), free_apic(), free_common(), free_link(), free_picture_tables(), free_side_data(), free_vsframe_ref(), h2645_sei_to_side_data(), handle_packets(), hevc_decode_flush(), hevc_decode_free(), hw_device_free_all(), hw_device_init_from_string(), hw_device_init_from_type(), hwdevice_ctx_free(), hwdownload_config_input(), hwdownload_uninit(), hwframe_ctx_free(), hwmap_config_output(), hwmap_uninit(), hwupload_config_output(), hwupload_query_formats(), hwupload_uninit(), iccdetect_uninit(), init_hwframe_ctx(), init_hwframes_ctx(), init_stage(), init_vpp_session(), input_callback(), jpegxl_anim_close(), jpegxl_anim_read_packet(), kmsgrab_read_close(), libdav1d_data_free(), libdav1d_picture_allocator(), libdav1d_picture_release(), libjxl_decode_close(), libjxl_get_icc(), libwebp_anim_encode_close(), LLVMFuzzerTestOneInput(), main(), make_table_writable(), mids_buf_free(), mpeg4_unpack_bframes_close_flush(), mpeg4_unpack_bframes_filter(), mpeg_decode_end(), mpegts_close_filter(), nppscale_uninit(), nppsharpen_config(), nppsharpen_uninit(), npptranspose_uninit(), nvdec_decoder_free(), nvdec_init_hwframes(), nvenc_retrieve_frame_data(), nvenc_store_frame_data(), opaque_uninit(), opencl_filter_set_device(), overlay_cuda_uninit(), pool_alloc_buffer(), prepare_input_packet(), qsv_create_mids(), qsv_decode_close_qsvcontext(), qsv_decode_preinit(), qsv_device_free(), qsv_frame_alloc(), qsv_frame_free(), qsv_frames_uninit(), qsv_init_child_ctx(), qsv_init_session(), qsvenc_init_session(), raw_close_decoder(), raw_decode(), rd_release(), read_close_vs(), read_packet_vs(), release_frame_buffer(), replace_side_data_from_buf(), reset_pes_packet_state(), rkmpp_release_decoder(), rkmpp_retrieve_frame(), scale_vt_config_output(), set_hwframe_ctx(), set_side_data(), test_derivation(), test_device(), transpose_vt_config_output(), transpose_vt_recreate_hw_ctx(), uninit(), update_context_from_thread(), v4l2_buf_to_bufref(), vaapi_encode_free(), vaapi_frames_init(), videotoolbox_buffer_release(), videotoolbox_postproc_frame(), vulkan_free_internal(), and vulkan_transfer_data().

◆ av_buffer_is_writable()

int av_buffer_is_writable ( const AVBufferRef buf)
1 if the caller may write to the data referred to by buf (which is true if and only if buf is the only reference to the underlying AVBuffer). Return 0 otherwise. A positive answer is valid until av_buffer_ref() is called on buf.

Definition at line 147 of file buffer.c.

Referenced by alloc_rbsp_buffer(), av_buffer_make_writable(), av_buffer_realloc(), av_frame_is_writable(), av_grow_packet(), av_packet_make_writable(), frame_data_ensure(), and make_table_writable().

◆ av_buffer_get_opaque()

void* av_buffer_get_opaque ( const AVBufferRef buf)
the opaque parameter set by av_buffer_create.

Definition at line 155 of file buffer.c.

◆ av_buffer_get_ref_count()

int av_buffer_get_ref_count ( const AVBufferRef buf)

Definition at line 160 of file buffer.c.

Referenced by ff_h264_build_ref_list().

◆ av_buffer_make_writable()

int av_buffer_make_writable ( AVBufferRef **  buf)

Create a writable reference from a given buffer reference, avoiding data copy if possible.

bufbuffer reference to make writable. On success, buf is either left untouched, or it is unreferenced and a new writable AVBufferRef is written in its place. On failure, buf is left untouched.
0 on success, a negative AVERROR on failure.

Definition at line 165 of file buffer.c.

Referenced by raw_decode().

◆ av_buffer_realloc()

int av_buffer_realloc ( AVBufferRef **  buf,
size_t  size 

Reallocate a given buffer.

bufa buffer reference to reallocate. On success, buf will be unreferenced and a new reference with the required size will be written in its place. On failure buf will be left untouched. *buf may be NULL, then a new buffer is allocated.
sizerequired new buffer size.
0 on success, a negative AVERROR on failure.
the buffer is actually reallocated with av_realloc() only if it was initially allocated through av_buffer_realloc(NULL) and there is only one reference to it (i.e. the one passed to this function). In all other cases a new buffer is allocated and the data is copied.

Definition at line 183 of file buffer.c.

Referenced by av_buffer_realloc(), av_grow_packet(), avcodec_default_get_encode_buffer(), evc_frame_merge_filter(), ff_parse_a53_cc(), jpegxl_anim_read_header(), mpeg_decode_a53_cc(), and packet_alloc().

◆ av_buffer_replace()

int av_buffer_replace ( AVBufferRef **  dst,
const AVBufferRef src 

Ensure dst refers to the same data as src.

When *dst is already equivalent to src, do nothing. Otherwise unreference dst and replace it with a new reference to src.

dstPointer to either a valid buffer reference or NULL. On success, this will point to a buffer reference equivalent to src. On failure, dst will be left untouched.
srcA buffer reference to replace dst with. May be NULL, then this function is equivalent to av_buffer_unref(dst).
0 on success AVERROR(ENOMEM) on memory allocation failure.

Definition at line 233 of file buffer.c.

Referenced by av1_receive_frame_internal(), av_frame_replace(), av_frame_side_data_clone(), av_packet_copy_props(), ff_decode_frame_props_from_pkt(), ff_encode_reordered_opaque(), ff_h2645_sei_ctx_replace(), ff_update_picture_tables(), ff_vk_update_thread_context(), flashsv_decode_frame(), flashsv_encode_frame(), frame_copy_props(), frame_data_submit(), iccdetect_filter_frame(), ifilter_parameters_from_frame(), libwebp_anim_encode_frame(), libx265_encode_frame(), setup_frame(), and vaapi_encode_send_frame().