RVDECAPI-FRD-1.0

RealVideo Decoder Interface Requirements

Revision History

Name

Date

Reason For Changes

Version

Milko Boic

12/06/2006

Initial version

1.0

1. Decoder Initialization Input Parameters

The following parameters must be passable to RealVideo decoder on initialization.

Syntax
Num Bits
Mnemonic

RVDecoderHeader(int header_len) {

media_object_format

32
4cc

codec_id

32
4cc

frame_width

16
uimbsf

frame_height

16
uimsbf

bit_count

16
uimsbf

pad_width

16
uimsbf

pad_height

16
uimsbf

if (media_object_format == 0x5649444F) {

frame_rate

32
uimbsf

bytes_left = header_len 22

} else {

bytes_left = header_len 18

}

for (i = 0; i < bytes_left; i++) {

codec_opaque_data_byte[i]

8
Bslbf(rv_codec_opaque_data)

}

}

Syntax
Num Bits
Mnemonic

rv_codec_opaque_data(codec_id) {

SPO_extra_flags

32
uimsbf

bitstream_major_version

4
uimsbf

bitstream_minor_version

8
uimsbf

bitstream_release_version

8
uimsbf

reserved

4
uimsbf

frontend_version

8
uimsbf

if (codec_id == 0x52563430) { /* RV 9 and 10 */

encode_size

32
uimsbf

}

}

header_len: size of the RVDecoderHeader structure in bytes

media_object_format: This 4cc field is either 0x5649444F (VIDO) or 0x494D4147 (IMAG). VIDO is most commonly used, and IMAG is only found in very old content with certain legacy codecs.

codec_id: 4cc which identifies the codec used in this substream. For RealVideo 1, codec_id is 0x52563130 (RV10). For RealVideo G2, codec_id is 0x52563230 (RV20). For RealVideo 8, codec_id is 0x52563330 (RV30). For RealVideo 9 and 10, codec_id is 0x52563430 (RV40).

frame_width: Width in pixels of a video frame

frame_height: Height in pixels of a video frame

bit_count: Number of bits per pixel

pad_width: Padded width in pixels of a video frame. In some cases, codecs need the frame width to be a multiple of a certain number, and therefore the frame width must be padded.

pad_height: Padded height in pixels of a video frame. In some cases, codecs need the frame height to be a multiple of a certain number, and therefore the frame height must be padded.

frame_rate: Frame rate of the video. This is a 32-bit fixed-point value in which the upper 16 bits are the integer part and the lower 16 bits are the fractional part.

codec_opaque_data_byte[i]: Byte i of the codec-specific opaque data.

SPO_extra_flags: Flags which provide internal information about the bitstream to the codec. These will be interpreted differently depending on the bitstream versions and the codec_id.

bitstream_major_version: Major version of the bitstream

bitstream_minor_version: Minor version of the bitstream.

bitstream_release_version: Release version of the bitstream. For codec_id = RV40 (RealVideo 9 and 10), this field is used to distinguish between RealVideo 9 and 10. If the bitstream_release_version >= 6, then this is RealVideo 10. Otherwise, this is RealVideo 9.

reserved: Reserved for future use. This should be ignored.

frontend_version: Version of the codec front-end.

encode_size: For RealVideo 9 and 10, this is the size in bytes of the largest encoded frame.

2. Decoder Initialization Output Parameters

The following parameters must be retrievable from the decoder (unless otherwise specified for a specific parameter) by the caller after the initialization and before any frame decode operation to determine the output format of the RealVideo decoder:

Syntax
Num Bits
Mnemonic

ulPadWidthLeft

32
uimsbf

ulPadWidthRight

32
uimsbf

ulPadHeightTop

32
uimsbf

ulPadHeightBottom

32
uimsbf

ulPictureHeight

32
uimsbf

ulPictureWidth

32
uimsbf

ulBitstreamVersion

32
uimsbf

ulPadWidthLeft: Number of pixels padded to the left of the picture

ulPadWidthRight: Number of pixels padded to the right of the picture

ulPadHeightTop: Number of pixels padded to the top of the picture

ulPadHeightBottom: Number of pixels padded to the bottom of the picture

ulPictureHeight: Picture height

ulPictureWidth: Picture width

ulBitstreamVersion: Bitstream version deduced form the initialization header. The support for this is not required but should be provided to allow proper error and upgrade handling.

3. Decoder Messages

3.1 Configuration Messages

The following messages should be transmittable to the decoder at or after the initialization and before any frame decode operations.

Message
Parameter

Name
Type

SP_POSTFILTER

bEnable
bool

SP_TEMPORALINTERP

bEnable
bool

SP_ALLOW_DIFFERENT_OUPUT_SIZES

bEnable
bool

Addition of new messages should be possible with arbitrary size and format of the associated parameters. Each message should be identified via a 32 bit unsigned integer and should be associable to a parameter of arbitrary size. If a particular message is not understood by the decoder, failure to accept the message must be returned to the caller.

It is acceptable for the configuration messages to be conveyed along with the initialization input parameters.

SP_POSTFILTER: FALSE = disable post filter; TRUE = enable post filter

SP_TEMPORALINTERP: FALSE = disable temporal interpolation; TRUE = enable temporal interpolation

SP_ALLOW_DIFFERENT_OUPUT_SIZES:

FALSE = scale varying picture size to the reported, consistent picture size

TRUE = output varying picture size and provide picture size with each docoded picture to allow caller to properly scale it

3.2. Dynamic Messages

The following messages must be transmittable to the decoder after the initialization and before or after any frame decode operations (unless indicated otherwise for a specific parameter):

Syntax
Parameter

Name
Type

SP_SEEK

ulSequenceStartTS
Uimsbf-32

SP_FLUSH

n/a
n/a

Addition of new messages should be possible with arbitrary size and format of the associated parameter. Each message should be identified via a 32 bit unsigned integer and should be associable with a parameter of arbitrary size. If a particular message is not understood by the decoder, failure to accept the message must be returned to the caller.

SP_SEEK: Informs the decoder to prepare for decoding of new picture sequence and identifies the starting RENDERING time-stamp in milliseconds. The frames fed into the decoder can precede the identified starting RENDERING time-stamp.

SP_FLUSH: Informs the decoder no more input is available and to generate all remaining output it can. This message can be optionally implemented as input of specially marked (with HXCODEC_DATA::lastPacket set to 1) coded frame into the decoder.

4. Decoder Input

Decoder frame input interface must support the following input structures:

Syntax
Num Bits
Mnemonic/Type

HXCODEC_DATA {

dataLength

32
uimbsf

dataPtr

CPU dep.
UINT8*

timestamp

32
uimbsf

sequenceNum

16
uimbsf

flags

16
uimsbf

lastPacket

16
uimsbf

numSegments

16
uimsbf

segments[numSegments]

64 * numSegments
Bslbf(HXCODEC_SEGMENTINFO)

}

Syntax
Num Bits
Mnemonic/Type

HXCODEC_SEGMENTINFO {

bIsValid;

32
uimsbf

ulSegmentOffset;

32
uimsbf

}

dataLength Length of data (in bytes) pointed to dataPtr

dataPtr Pointer to memory buffer containing coded picture data. Can be NULL (0) when dataLength is 0. It is acceptable for this field to be replaced by a 32-bit byte offset from the start of HXCODEC_DATA structure.

timestamp Coded frame presentation timestamp in milliseconds

sequenceNumber Coded frame sequence number.

flags Reserved

lastPacket 0 = non-last coded frame, 1 = last coded frame in sequence.

numSugments Number of segments present in data pointed to by dataPtr and number HXCODEC_SEGMENTINFO structures following and describing the location of the segments

bIsValid 0 = segment is not valid (corrupted or missing), 1 = segment is valid

ulSegmentOffset Byte offset to the beginning of the segment from the start of dataPtr indicated buffer.

5. Decoder Output

Decoder output must not be assumed to be produced on input of a coded frame. That is, decoder must be allowed to defer producing output on given input.

Decoder must be able to produce multiple video frames on given input.

With each produced decode frame, the decoder must be able to output the following parameters (unless indicated otherwise for the specific parameter):

Syntax
Num Bits
Mnemonic/Type

bModifiedPictureStart

>=1
bool

ulDecodedPictureHeight

32
uimsbf

ulDecodedPictureWidth

32
uimsbf

ulPicturePresentationTS

32
uimsbf

uSequenceNum

16
uimsbf

bModifiedPictureSize 0 = Picture size does not differ from the picture size communicated on initialization, 1 = Picture size differs from the picture size communicated on initialization and it is supplied via ulDecodedPictureHeight and ulDecodedPictureWidth parameters. This parameter need not be supported if SP_ALLOW_DIFFERENT_OUPUT_SIZES support is disabled as well.

ulDecodedPictureHeight

ulDecodedPictureWidth Height and width in pixels of the decoded picture which can be different from ulPictureHeight/ulPictureWidth provided upon initialization. If different, caller must scale the decoded picture to the lPictureHeight/ulPictureWidth before displaying. This parameter need not be supported if SP_ALLOW_DIFFERENT_OUPUT_SIZES support is disabled as well.

ulPicturePresentationTS Decoded picture presentation time stamp

uSequenceNum Decoded picture sequence number is not required but should be provided to allow identification of dropped frames for statistical purposes