[−][src]Function ffmpeg_sys_next::avcodec_get_hw_frames_parameters

pub unsafe extern "C" fn avcodec_get_hw_frames_parameters(
    avctx: *mut AVCodecContext, 
    device_ref: *mut AVBufferRef, 
    hw_pix_fmt: AVPixelFormat, 
    out_frames_ref: *mut *mut AVBufferRef
) -> c_int

Create and return a AVHWFramesContext with values adequate for hardware decoding. This is meant to get called from the get_format callback, and is a helper for preparing a AVHWFramesContext for AVCodecContext.hw_frames_ctx. This API is for decoding with certain hardware acceleration modes/APIs only.

The returned AVHWFramesContext is not initialized. The caller must do this with av_hwframe_ctx_init().

Calling this function is not a requirement, but makes it simpler to avoid codec or hardware API specific details when manually allocating frames.

Alternatively to this, an API user can set AVCodecContext.hw_device_ctx, which sets up AVCodecContext.hw_frames_ctx fully automatically, and makes it unnecessary to call this function or having to care about AVHWFramesContext initialization at all.

There are a number of requirements for calling this function:

  • It must be called from get_format with the same avctx parameter that was passed to get_format. Calling it outside of get_format is not allowed, and can trigger undefined behavior.
  • The function is not always supported (see description of return values). Even if this function returns successfully, hwaccel initialization could fail later. (The degree to which implementations check whether the stream is actually supported varies. Some do this check only after the user's get_format callback returns.)
  • The hw_pix_fmt must be one of the choices suggested by get_format. If the user decides to use a AVHWFramesContext prepared with this API function, the user must return the same hw_pix_fmt from get_format.
  • The device_ref passed to this function must support the given hw_pix_fmt.
  • After calling this API function, it is the user's responsibility to initialize the AVHWFramesContext (returned by the out_frames_ref parameter), and to set AVCodecContext.hw_frames_ctx to it. If done, this must be done before returning from get_format (this is implied by the normal AVCodecContext.hw_frames_ctx API rules).
  • The AVHWFramesContext parameters may change every time time get_format is called. Also, AVCodecContext.hw_frames_ctx is reset before get_format. So you are inherently required to go through this process again on every get_format call.
  • It is perfectly possible to call this function without actually using the resulting AVHWFramesContext. One use-case might be trying to reuse a previously initialized AVHWFramesContext, and calling this API function only to test whether the required frame parameters have changed.
  • Fields that use dynamically allocated values of any kind must not be set by the user unless setting them is explicitly allowed by the documentation. If the user sets AVHWFramesContext.free and AVHWFramesContext.user_opaque, the new free callback must call the potentially set previous free callback. This API call may set any dynamically allocated fields, including the free callback.

The function will set at least the following fields on AVHWFramesContext (potentially more, depending on hwaccel API):

  • All fields set by av_hwframe_ctx_alloc().
  • Set the format field to hw_pix_fmt.
  • Set the sw_format field to the most suited and most versatile format. (An implication is that this will prefer generic formats over opaque formats with arbitrary restrictions, if possible.)
  • Set the width/height fields to the coded frame size, rounded up to the API-specific minimum alignment.
  • Only if the hwaccel requires a pre-allocated pool: set the initial_pool_size field to the number of maximum reference surfaces possible with the codec, plus 1 surface for the user to work (meaning the user can safely reference at most 1 decoded surface at a time), plus additional buffering introduced by frame threading. If the hwaccel does not require pre-allocation, the field is left to 0, and the decoder will allocate new surfaces on demand during decoding.
  • Possibly AVHWFramesContext.hwctx fields, depending on the underlying hardware API.

Essentially, out_frames_ref returns the same as av_hwframe_ctx_alloc(), but with basic frame parameters set.

The function is stateless, and does not change the AVCodecContext or the device_ref AVHWDeviceContext.

@param avctx The context which is currently calling get_format, and which implicitly contains all state needed for filling the returned AVHWFramesContext properly. @param device_ref A reference to the AVHWDeviceContext describing the device which will be used by the hardware decoder. @param hw_pix_fmt The hwaccel format you are going to return from get_format. @param out_frames_ref On success, set to a reference to an uninitialized AVHWFramesContext, created from the given device_ref. Fields will be set to values required for decoding. Not changed if an error is returned. @return zero on success, a negative value on error. The following error codes have special semantics: AVERROR(ENOENT): the decoder does not support this functionality. Setup is always manual, or it is a decoder which does not support setting AVCodecContext.hw_frames_ctx at all, or it is a software format. AVERROR(EINVAL): it is known that hardware decoding is not supported for this configuration, or the device_ref is not supported for the hwaccel referenced by hw_pix_fmt.