ref_iface_IVDXVideoDecoder_DecodeFrame - shekh/VirtualDub2 GitHub Wiki

VirtualDub Plugin SDK 1.2

IVDXVideoDecoder interface

IVDXVideoDecoder:: DecodeFrame

Decodes a sample, possibly producing a frame in the current framebuffer.

const void *DecodeFrame(const void *inputBuffer, uint32 data_len, bool is_preroll, sint64 sampleNumber, sint64 targetSample);

Parameters

inputBuffer	Pointer to the sample data. This may be NULL if `data_len` is zero; otherwise, it must point to a DWORD-aligned buffer with at least `data_len` bytes, followed by the number of padding bytes indicated by GetDecodePadding().
data_len	The number of bytes in the sample data.
is_preroll	True if the sample should be decoded to internal buffers only; false if the image data should also be decoded to the framebuffer.
sampleNumber	The number of the sample provided for decoding, or -1 if no sample is provided.
targetSample	The sample number of the frame being targeted by the sequence of samples being decoded.

Thread safety

This method is not thread-safe.

Errors

Errors may not be returned from this function (see SetError()).

Return value

If is_preroll is false, a pointer to the framebuffer base (see GetFrameBuffer() for details).

Remarks

In general, the host will call GetNextRequiredSample(), read the required samples, and feed the samples one at a time to this routine until the frame is decoded; is_preroll will be true except for the last sample. Note that it is possible for the host to stop sending samples and start decoding toward another frame, so the decoder must have well-defined state after each sample, although possibly non-optimal.

A call to DecodeFrame() with inputBuffer == NULL, data_len == 0, is_preroll == false, and sampleNumber == -1 indicates a request to decode a frame that is already resident in an internal buffer. The host will issue a call like this when the video decoder model reports no samples are required to decode a frame. This is mainly required for decoders that support B frames, where a frame may need to be re-converted from an internal framebuffer. It can also be used to support caching of expensive frames in I and I/P decoding models, however.

Decoders must not read beyond the end of the buffer. The GetDecodePadding() method allows the decoder to request additional padding at the end of the buffer to ease decoding; this extra space is not initialized to any particular value and is not included in data_len. Reading beyond data_len + GetDecodePadding() is an extremely bad idea and will result in random crashes.