This code and information is provided "as is" without warranty of any kind, either expressed or implied, including but not limited to the implied warranties of merchantability and/or fitness for a particular purpose.

1995,1998 Analog Devices, Inc.

# Interface for MMX-based ADV601 Software codec

Currently (4/18/98) only the decoder part works.

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

  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:

     `line_stride`
       The distance samples, or bytes, 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 * 2` (the last, modified, value of it). This value must always be a multiple of 8 .
     `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.
     `interlace_p`
       If non-zero, the decoder doubles the `line_stride` and offsets the first line depending on the field number. Note that to decode one frame one has to call `decompress_field` twice: once for each field.
     `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.
     `vitc`

  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.