int more = DecodeVideoFrame(APTR handle, APTR packet,
               struct DecodeVideoFrameCtrl *ctrl);

Hollywood will pass a pointer to a struct DecodeVideoFrameCtrl structure to this function. This structure looks like the following:

struct DecodeVideoFrameCtrl { UBYTE **Buffer; // [in/out] int *BufferWidth; // [in/out] int Delay; // [out] ULONG Offset; // [out] double PTS; // [out] double DTS; // [out] };

If you return True to indicate that you are not able to decode a full frame just yet, you don't have to write anything to the struct DecodeVideoFrameCtrl pointer passed to you by Hollywood. Otherwise you have to set the following members:

Buffer:

This is already initialized to an array of three UBYTE* pointers. You need to set these pointers to the chunks of memory containing the actual pixel data of the decoded frame. If you have set the PixFmt member in OpenVideo() to HWVIDPIXFMT_ARGB32, you only need to set the first pointer because ARGB32 frames are stored as chunky pixels. If you use HWVIDPIXFMT_YUV420P, though, you need to set all three pointers to point to the individual YUV planes, i.e.

ctrl->Buffer[0] = y_plane; ctrl->Buffer[1] = u_plane; ctrl->Buffer[2] = v_plane;

Make sure that you do not modify the base Buffer pointer! You must only write to the individual three pointers already allocated for you by Hollywood.

BufferWidth:

This is already initialized to an array of three integers. You need to store the byte length of one row of pixel data for each pixel map you pass. If you have set the PixFmt member in OpenVideo() to HWVIDPIXFMT_ARGB32, you only need to set the first integer to the byte width of a single row of ARGB32 pixel data because ARGB32 frames are stored as chunky pixels. If you use HWVIDPIXFMT_YUV420P, though, you need to set all three integers to point to the byte width of a single row in each of the three individual YUV planes, i.e.

ctrl->BufferWidth[0] = y_plane_bytewidth; ctrl->BufferWidth[1] = u_plane_bytewidth; ctrl->BufferWidth[2] = v_plane_bytewidth;

Make sure that you do not modify the base BufferWidth pointer! You must only write to the individual integer array items already allocated for you by Hollywood.

Delay:

This member can be used to specify an additional delay for the video frame. The delay you specify here is multiplied by the FrameTime specified in OpenVideo() divided by two. So to delay the current frame for one FrameTime unit, you'd have to set this member to 2. This should normally be set to 0.

Offset:

This must be set to the current offset in the video stream in bytes. This is only required if SeekMode in OpenVideo() has been set to HWVIDSEEKMODE_BYTE. If that is not the case, you can set this member to 0.

PTS:

This must be set to the video frame's presentation time stamp, i.e. the time when this frame should be presented to the viewer, relative to the beginning of the video stream. You have to specify this time stamp as a floating point number in seconds, i.e. a presentation time stamp of 10.2 means that the frame is to be shown 10.2 seconds after the start of the video stream. The value you pass in PTS must be a multiple of the FrameTime fraction specified in OpenVideo().

DTS:

This should normally be set to -1. You only need to set this to a time stamp if the frame's presentation order is different from the encoding order. In that case you need to set this member to the decoding time stamp. As above, PTS also needs to be specified as a floating point number in seconds.

This function must be implemented in a thread-safe way.

handle

handle returned by OpenVideo()

packet

pointer to a packet allocated by NextPacket()

ctrl

pointer to a struct DecodeVideoFrameCtrl to be filled out by the function

more

True if function needs more packets to decode a frame, False if it has successfully decoded a frame