1995,1998 Analog Devices, Inc.

Interface for MMX-based ADV601 Software codec

Decoder Interface

Functions

init_decompress_field

Does not do any decompression, but has to be called just once before any actual decompression can happen.

decompress_field

Decompresses one field at a time.

Arguments

All arguments are passed as elements of one structure data type called ADV6PARMS.

1. Before calling init_decompress_field the following fields must be set:

   full_width

   This has to be set to the full width of the image. This can be larger then the displayed size when the image is scaled for display.

   full_height

   Similarly, this is the full size of the original image, and it can be different from the width of the displayed image.

   display_width

   This is the requested width of the displayed image. The decoder modifies this value during the initialization. (see below for details).

   display_height

   Similarly to display_width, this is only the requested height of the displayed image, which the decoder can modify.

   compressed_data

   This must point to the beginning of the compressed data. That area must contain at least the whole field worth of compressed data.

   compressed_data_size

   The size of the compressed data in bytes. On return this field contains the actuall size.

2. On the return from init_decompress_field the decoder sets or modifies the following fields:

   display_width

   display_height

   These will be modified to make it convenient for fast decoding. The resulting size will be close to the requested, but the exact values depend, among other things, on the implementation. See here for more details.

   work_area_size

   Amount of extra memory in bytes the decoder needs to do the job. This does not include memory occupied by compressed or decompressed data.

   status_flag

   This is set to OK if there are no problems during the initialization, otherwise the flag indicates the problem. An example of a problem during the initialization: the image is too small.

3. Before decompress_field can be called, the following fields of the ADV6PARMS structure must be set:

   line_stride

   The distance in pixels from the beginning of one line of the displayed image to the beginning of the next line. This is used when the decoder writes directly to video memory, in which case the line_stride is the width of the whole screen. If, on the other hand, the decoder writes to contiguous memory, then line_stride = display_width (the last, modified, value of it). This value must always be a multiple of 4 .

   work_area_address

   This must be set to the beginning of the work area which has at least work_area_size bytes.

   decompressed_data

   Address of the area to which the decoder writes decompressed data in UYVY format (4:2:2 YUV). Often this will point to the beginning of the window in the video memory to make really efficient playback.

   output_sample_order

   This is an enumeration type with possible values of A6SORD_UYVY, A6SORD_VYUY, A6SORD_YUYV and A6SORD_YVYU. This parameter defines the format of the output from the decoder. Currently all are of 4:2:2 type, but they differ in the order of color samples in the output (see the table).

   interlace_p

   If non-zero, the decoder doubles the line_stride and offsets the first line depending on the field number.

   contiguous_data_p

   When this is non-zero, the decoder continues decoding the bit stream started at the previous field. Using this flag one can use the decoder on AVI files in which two fields are groupped into single frame. In this situation the caller does not have to find the beginning of the second field.

   Normal use of this flag:

   • For non-interlaced images or when each field is stored separately the caller reads one field at a time and sets contiguous_data_p to 0 for each call to the decoder.
   • For interlaced videos in which two fields are groupped together into one frame and it is difficult for the caller to find the beginning of the second field, both fields must be read together into the buffer, then 2 calls must be made to the decoder, the first time contiguous_data_p must be set to 0, the second time -- to 1.

4. During decompress_field the decoder sets the following data:

   status_flag

   Set to OK if there were no problems during decoding.

   field_num

   This field is 0 for the bottom field and 1 for the top field. This is relevant for interlaced images only.

   actual_data_size

   This is the size in bytes of the decoded field. Whoever calls the decoder can then use this value to find the beginning of the next field in the bitstream. Note that this value is normally smaller than that of compressed_data_size.

5. After the last call to decompress_field the caller is responsible for freeing all the memory allocated including the work area used by the decoder.

Notes

• Displayed ("Real") Image Width can be different from the requested image size. Currently its width must be multiple of 4, the height is the same. The modification consists of two steps: (Note: these details are likely to change in the future.)
  1. In the first step the size is determined purely by the geometry of the wavelet transform. The decoder finds the image size which is different by the factor of 2 from the full size. At the first stage only width is scaled by 2, then during consequent stage both widths and heights are scaled. When scaling an odd number, the rounding is always up. For example, if the filed size is 720x243 (North American NTSC format), then possible scaled sizes are
     • 360 x 243
     • 180 x 122
     • 90 x 61
     • 45 x 31
     • 23 x 16
     From this set the decoder chooses the one with the biggest width below the requested one. For example, if the display_width is set by the caller to 340, the decoder chooses 180x122.
  2. In the second step the decoder modifies these parameters to allow more efficient MMX implementation. Currently (3/27/98) all it does is rounding the display_width down to a multiple of 8. For example, 180x122 would be modified to 176x122.
• The Compressed Data for the whole field must fit in contiguous memory (otherwise we would have to establish the protocol for refilling the memory).
• The caller is responsible for allocating and freeing the memory for working areas.
• Encoder and decoder are separate execution units. Currently only the decoder part works. In the near future the encoder will be implemented in floating point only thus making it much slower than the decoder, which is implemented using MMX.
• Interlaced fields are processed by the coder (it writes to every other line when the interlaced_p flag is set, but the caller is responsible for allocating enough memory, setting the interlace flag and providing the field number.
• The sample order for different formats is listed here for the reference:

  Code	Order
  UYVY	U0	Y0	V0	Y1	U2	Y2	V2	Y3
  VYUY	V0	Y0	U0	Y1	V2	Y2	U2	Y3
  YUYV	Y0	U0	Y1	V0	Y2	U2	Y3	V2
  YVYU	Y0	V0	Y1	U0	Y2	V2	Y3	U2