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.
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.