











                    USER'S GUIDE TO JPEG API FOR AUDIO CARDS







                                 June 29, 1992



















































  PREFACE
  _______





                         This  package  implements  the JPEG baseline standard.
                      The primary algorithm  is  subroutine  JPEG_base()  which
                      does  compression  or decompression with or without color
                      conversion on images which are in pixel  format,  without
                      headers.

                         In  order  to facilitate implementation, JPEG_base()'s
                      interface to pixels is through buffers.    These  buffers
                      are  created  and  set to optimum maximal sizes up to 64K
                      bytes by JPEG_base.   The size is restricted  to  64K  so
                      that  JPEG_base  will run under OS/2, Windows or DOS with
                      no performance degradations.

                         Partial  optimization  occurs  for  the  more   common
                      formats of:

                      o   YUV

                      o   RGB 888

                      o   YYUV

                      o   monochrome

                      With  degradation  in  performance,  the  algorithm  will
                      handle images

                      o   which are interleaved or non-interleaved

                      o   with any number of components from one to four

                      o   with any number of samples from one to four in either
                          the vertical or horizontal direction for any  of  the
                          components.

                      o   which  have the same number of samples of each compo-
                          nent in every MDU

                         Note that this last bullet  does  not  apply  to  YYUV
                      images  with  odd number of columns.  In these cases, the
                      API expects the last MDU of each  row  to  contain  three
                      samples:  YUV as per the JPEG standard.

                         For non-optimized image formats, this last bullet is a
                      restriction not imposed by the JPEG standard.  Two tuples
                      of component samples for which this is not a problem are:




  ii  User's Guide to JPEG API for Audio Cards









                      3 SAMPLES IN ONE COMPONENT AND 1 - 4 SAMPLES OF ANOTHER
                          COMPONENT IN THE SAME DIMENSION, (EITHER WIDTH OR
                          HEIGHT).
                          where  the  size  of the image in that dimension is a
                          factor of primes, at least one of which is 3.

                      4 SAMPLES IN ONE COMPONENT AND 2 SAMPLES OF ANOTHER COM-
                          PONENT IN THE SAME DIMENSION
                          where the size of the image in that  dimension  is  a
                          multiple of 4.

                      For every other instance of two tuples from non-optimized
                      formats,  within a corresponding image, the last MDU of a
                      row or column will contain a different number of  samples
                      per component from the other MDUs of the image.

                         Color conversion can be done within JPEG_base(), or it
                      can be accomplished by the standalone utility:  colorcon.
                      Color  conversion  is limited to a subset of the possible
                      color spaces, but most of the more popular  color  spaces
                      are  supported  including RGB 565 which is the 16 bit RGB
                      image format supported by XGA Direct Color mode.

                         When  compressing  an  image,  information  about  the
                      image,  quantization  tables, Huffman tables, components,
                      sample ratios, restart intervals, etc. is contained in an
                      input parameter file written according to the  specifica-
                      tions  in  the  JPEG standard. Sample parameter files are
                      provided as part of the package, and two utilities:

                      1.  GETPARAM -- which reads a parameter file and  reports
                          requested information

                      2.  SETPARAM  --  which  changes  information  in or adds
                          information to a parameter file.

                      are provided so that a  user  may  create  new  parameter
                      files  to  match  image  files they may wish to compress.
                      When a coefficient file is decompressed to form an image,
                      the JPEG segment information within the coefficient  file
                      is combined to form an output parameter file.















                                                                   Preface  iii

































































  iv  User's Guide to JPEG API for Audio Cards









  CONTENTS
  ________





                      1.0  OVERVIEW  . . . . . . . . . . . . . . . . . . . .  1

                      2.0  JPEG COMPRESSION/DECOMPRESSION ROUTINE  . . . . .  4
                      2.1  Compression   . . . . . . . . . . . . . . . . . .  4
                      2.2   Decompression  . . . . . . . . . . . . . . . . .  5
                      2.3   Return Codes   . . . . . . . . . . . . . . . . .  5
                      2.4   ComArea  . . . . . . . . . . . . . . . . . . . .  6
                        2.4.1   Structure  . . . . . . . . . . . . . . . . .  6
                        2.4.2   Definition   . . . . . . . . . . . . . . . .  7
                          2.4.2.1  BegAreaID   . . . . . . . . . . . . . . .  7
                          2.4.2.2   Operation  . . . . . . . . . . . . . . .  7
                          2.4.2.3   Color Spaces   . . . . . . . . . . . . .  8
                          2.4.2.4   Warning and Error Parameters   . . . . .  9
                          2.4.2.5   SampleCode   . . . . . . . . . . . . .   11
                          2.4.2.6   EndAreaID  . . . . . . . . . . . . . .   11
                      2.5   Pixel Buffer   . . . . . . . . . . . . . . . .   11
                        2.5.1   Structure  . . . . . . . . . . . . . . . .   11
                        2.5.2   Definition   . . . . . . . . . . . . . . .   11

                      3.0  BUFFERING   . . . . . . . . . . . . . . . . . .   13
                      3.1   Multiple Buffering Protocol  . . . . . . . . .   13
                        3.1.1   Compression  . . . . . . . . . . . . . . .   13
                        3.1.2   Decompression  . . . . . . . . . . . . . .   14

                      4.0  COLOR CONVERSION ROUTINE  . . . . . . . . . . .   16
                      4.1   Parameters   . . . . . . . . . . . . . . . . .   17

                      5.0  COLOR SPACE CONVERSION PROGRAM: COLORCON.EXE  .   18

                      6.0  ERROR AND WARNING CODES REFERENCE   . . . . . .   19
                      6.1   ERRORS   . . . . . . . . . . . . . . . . . . .   19
                        6.1.1   External Errors  . . . . . . . . . . . . .   19
                        6.1.2   Internal Errors  . . . . . . . . . . . . .   22
                      6.2  WARNINGS  . . . . . . . . . . . . . . . . . . .   25
                        6.2.1   The following warnings set the
                         IMAGE_FRAME_WARN flag:  . . . . . . . . . . . . .   26
                        6.2.2   The following warnings set the COMPONENT
                         flag:   . . . . . . . . . . . . . . . . . . . . .   26
                        6.2.3   The following warnings set the SCAN flag:    26
                        6.2.4   The following warnings set the JPEG_TAB
                         flag:   . . . . . . . . . . . . . . . . . . . . .   27
                        6.2.5   The following warnings set the HUFF_TAB
                         flag:   . . . . . . . . . . . . . . . . . . . . .   27
                        6.2.6   The following warnings set the QUANT_TAB
                         flag:   . . . . . . . . . . . . . . . . . . . . .   29
                        6.2.7   The following warnings set the SAMPLES
                         flag:   . . . . . . . . . . . . . . . . . . . . .   29



                                                                    Contents  v









                        6.2.8   The following warnings set the DNL_WARN
                         flag:   . . . . . . . . . . . . . . . . . . . . .   29
                        6.2.9   The following warnings set the PARS flag:    29

                      7.0  JPEG PARAMETER MANIPULATION PROGRAMS: SETPARAM
                       AND GETPARAM  . . . . . . . . . . . . . . . . . . .   30
                      7.1   SETPARAM Utility   . . . . . . . . . . . . . .   30
                        7.1.1   Possible values of <action>:   . . . . . .   30
                        7.1.2   Actions and variable parameters:   . . . .   32
                      7.2   GETPARAM Utility   . . . . . . . . . . . . . .   33
                        7.2.1   Actions, variable parameters and the
                         response of GETPARAM:   . . . . . . . . . . . . .   33

                      8.0  DEPENDENCIES  . . . . . . . . . . . . . . . . .   36
                      8.1   Hardware   . . . . . . . . . . . . . . . . . .   36
                      8.2   Software   . . . . . . . . . . . . . . . . . .   36

                      9.0  SUBDIRECTORY CONTENTS   . . . . . . . . . . . .   37
                      9.1   JPEG\SOURCE Subdirectory with sample source
                       code  . . . . . . . . . . . . . . . . . . . . . . .   37

                      10.0  LIMITATIONS  . . . . . . . . . . . . . . . . .   39


































  vi  User's Guide to JPEG API for Audio Cards









  1.0   OVERVIEW
  ______________





                         The  proposed  Joint Photographic Experts Group (JPEG)
                      international standard specifies a set of  still  picture
                      gray  scale  and color image data compression algorithms.
                      The routines  included  in  this  package  implement  the
                      baseline system described in the JPEG Draft International
                      Standard.  The  proposed  standard is still under review,
                      and the final version may differ from the current draft.

                         The  standard  is  applicable  to  continuous-tone   -
                      greyscale  or  color  -  digital  still image data. It is
                      applicable to a wide range of applications which  require
                      the  use  of  compressed  images. It is not applicable to
                      bi-level image data. This standard  does  not  specify  a
                      complete coded image representation. Such representations
                      can  include  certain  parameters,  such  as pixel aspect
                      ratio  or  color  space  designation,   which   are   not
                      application-independent.

                         The  standard  defines a baseline system which guaran-
                      tees that a reasonable level of function will be  present
                      in  all  decoders which use the Discrete Cosine Transform
                      (DCT) algorithms. This baseline system uses a constrained
                      version of the sequential DCT compression algorithms.  In
                      this mode, individual sections of the image are coded and
                      stored  or  distributed  before  continuing with the next
                      section.

                         The basic encoding/decoding system can be  represented
                      as shown in Figure 1 on page 2

                         More  information on the proposed JPEG standard can be
                      obtained by requesting the JPEG  Technical  Specification
                      Committee Draft (ISO CD 10918-1) from the X3 Secretariat,
                      Computer  and  Business  Equipment Manufacturers' Associ-
                      ation, 311 First Street NW, Washington, DC 20001-2178.  A
                      general overview article appeared in the April 1991 issue
                      of  Communications  of the ACM (Volume 34, Number 4). The
                      article is "The JPEG Still Picture Compression  Standard"
                      by Gregory K. Wallace.

                         We  are providing facilities to use the digital signal
                      processor (DSP) on the IBM M-Audio Capture  and  Playback
                      Adapter/A  to do the image compression and decompression.
                      In addition, some color space  conversions  can  be  per-
                      formed  between  RGB  and YUV or YYUV color spaces. Color
                      conversion routines assume that the image data is  inter-
                      leaved.



                                                                    OVERVIEW  1









  -----------------------------------------------------------------------------

        Original Image                     Reconstructed Image
      +--------+--------+                  +--------+--------+
      |ENCODER |        |                  |DECODER |        |
      |  +-------------+|                  |  +-------------+|
      |  | Forward DCT ||                  |  | Inverse DCT ||
      |  | (8X8 Matrix)||                  |  | (8X8 Matrix)||
      |  +-------------+|                  |  +-------------+|
      |        |        |                  |        |        |
      |   +------------+|                  |   +------------+|
      |   |Quantizer   ||                  |   |Dequantizer ||
      |   +------------+|                  |   +------------+|
      |        |        |                  |        |        |
      |   +------------+|                  |   +------------+|
      |   |Huffman     ||                  |   |Huffman     ||
      |   |Coder       ||                  |   |Decoder     ||
      |   +------------+|                  |   +------------+|
      |        |        |                  |        |        |
      +--------+--------+                  +--------+--------+
          Coded Image ------------------------ Coded Image


  -----------------------------------------------------------------------------
  Figure 1. JPEG Base Encoding/Decoding Schematic

                         There are two versions of the DLL:

                      1.  one for OS/2 and

                      2.  one for Microsoft Windows

                      There are three versions of the API:

                      1.  a DLL for OS/2 1.2/1.3

                      2.  a DLL for Microsoft Windows 3.0 (standard or enhanced
                          modes)

                      3.  a LIB for coding DOS programs.

                      All  use  the  same interface. The end result produced by
                      the compression/ decompression routine is either  a  com-
                      pressed  image  file,  or  decompressed  image  data in a
                      buffer.

                         The routine provided uses the DSP  to  do  the  cosine
                      transforms  and  quantization/dequantization. The Huffman
                      encoding/decoding  is  done  on  the  host  PS/2   micro-
                      processor.

                         Three additional utilities are provided:




  2  User's Guide to JPEG API for Audio Cards









                      1.  The SETPARAM utility will change signal parameters in
                          a JPEG parameter file.

                      2.  The  GETPARAM utility will write the information con-
                          tained in a JPEG parameter file into a text file.

                      3.  The COLORCON utility will convert  a  file  of  pixel
                          data from one color space to another.

                      These  utilities  are family API programs that can be run
                      under DOS or OS/2.













































                                                                    OVERVIEW  3









  2.0   JPEG COMPRESSION/DECOMPRESSION ROUTINE
  ____________________________________________





                         The API for the Compression/Decompression routine is:

                      int   JPEG_base (int JPEGHandle,
                                       int CoefHandle,
                                       BUFFER far* far* PixelBuffer
                                       COM_AREA *ComArea)

                         This routine parses the JPEG markers and signal param-
                      eters  and, according to the information in them, acts to
                      either compress an image or decompress the  corresponding
                      coefficients.  Detailed  discussions  of  the ComArea and
                      PixelBuffer appear  in  separate  sections  below.  Brief
                      descriptions  of the parameters for the two cases of com-
                      pression and decompression are:


  2.1  COMPRESSION
  ________________

                      JPEGHANDLE
                          The file handle of a file that contains an input JPEG
                          parameter file with  markers  and  signal  parameters
                          which  determine  how  the image is to be compressed.
                          The data in this file is combined  with  the  coeffi-
                          cients  that  result  from compression to produce the
                          compressed coefficient file specified by CoefHandle.

                      COEFHANDLE
                          The file handle of the file  that  will  contain  the
                          output  JPEG  markers,  signal parameters and coeffi-
                          cients produced by compression. The coefficients from
                          each scan are placed after the signal parameters  for
                          that scan.

                      PIXELBUFFER
                          A  pointer to a buffer address. The buffer is created
                          by JPEG_base(). The user places image data into  this
                          buffer.

                      COMAREA
                          A  pointer to the communications area structure. This
                          structure contains information about operations to be
                          performed, color space conversions, and  warning  and
                          error messages.







  4  User's Guide to JPEG API for Audio Cards









  2.2   DECOMPRESSION
  ___________________

                      JPEGHANDLE
                          The  file handle of a file that will contain the JPEG
                          markers and signal parameters derived from the infor-
                          mation found in the  input  coefficient  file  during
                          decompression.  This  file may then be used to recom-
                          press the image or to compress a different image file
                          in the same manner.

                      COEFHANDLE
                          The file handle of the file that contains  the  input
                          JPEG  markers,  signal parameters and coefficients to
                          be decompressed.

                      PIXELBUFFER
                          A pointer to a buffer address. The buffer is  created
                          by JPEG_base() and is filled with pixels. JPEG_base()
                          fills  in  the address of the buffer for further user
                          action.

                      COMAREA
                          A pointer to the communications area structure.  This
                          structure contains information about operations to be
                          performed,  color  space conversions, and warning and
                          error messages.


  2.3   RETURN CODES
  __________________

                         JPEG_base() will  return  one  of  the  following  int
                      return codes:

                      0
                          Successful execution

                      1
                          Warnings were generated

                      -1
                          Unrecoverable error and possibly warnings

                         Details  of  the  cause  of a non-zero return code are
                      available in the communication area structure. A detailed
                      description of the errors and warnings is  given  in  the
                      Error and Warning Codes Reference section.










                                      JPEG COMPRESSION/DECOMPRESSION ROUTINE  5









  2.4   COMAREA
  _____________



  2.4.1   STRUCTURE

                           typedef struct com_area ¤
                              char        BegAreaID [ 10 &rbrk;
                              USHORT      operation;
                              USHORT      InputColorSpace;
                              USHORT      OutputColorSpace;
                              WARN_ELE    error;
                              USHORT      warning_flags;
                              WARN_STRUCT warnings;
                              USHORT      SampleCode;
                              char        EndAreaID [ 10 &rbrk;
                           ‡ COM_AREA;


                           typedef struct warn_ele ¤
                              USHORT WarnErrorCode;
                              USHORT data_element;
                              int    data_value;
                           ‡ WARN_ELE;



                           typedef struct warn_struct ¤
                               WARN_ELE *ImageFrame;
                               WARN_ELE *Component;
                               WARN_ELE *Scan;
                               WARN_ELE *JPEG_Tab;
                               WARN_ELE *HuffTab;
                               WARN_ELE *QuantTab;
                               WARN_ELE *Samples;
                               WARN_ELE *DNL;
                               WARN_ELE *Pars;

                               USHORT     NumImageFrame;
                               USHORT     NumComponent;
                               USHORT     NumScan;
                               USHORT     NumJPEG_Tab;
                               USHORT     NumHuffTab;
                               USHORT     NumQuantTab;
                               USHORT     NumSamples;
                               USHORT     NumDNL;
                               USHORT     NumPars;
                           ‡ WARN_STRUCT;








  6  User's Guide to JPEG API for Audio Cards









  2.4.2   DEFINITION



  2.4.2.1  BegAreaID

                         This  is  a  pointer to a null-terminated ASCII string
                      that must be set by the caller to "ComArea". It  is  used
                      to  verify  the  integrity of the ComArea as it is passed
                      along to different functions.


  2.4.2.2   Operation

                         A string of bits that consists of the logical union of
                      fields for:

                      +---------------------------+---------------------------+
                      | FLAG                      | VALUE                     |
                      +---------------------------+---------------------------+
                      | Compress/Decompress       | COMPRESS or DECOMPRESS    |
                      +---------------------------+---------------------------+
                      | Color Conversion          | NO_COLOR_CONVERT or       |
                      |                           | COLOR_CONVERT             |
                      +---------------------------+---------------------------+
                      | Call Sequence             | START_IMAGE,              |
                      |                           | INTERMEDIATE_SCAN,        |
                      |                           | END_OF_SCAN or            |
                      |                           | END_OF_IMAGE              |
                      +---------------------------+---------------------------+
                      | Number of Pixel Buffers   | SINGLE_BUFFER or          |
                      |                           | MULTIPLE_BUFFER           |
                      +---------------------------+---------------------------+

                      COMPRESS/DECOMPRESS

                      COMPRESS
                          indicates that  compression  is  performed  on  Pixel
                          Buffers to produce a coefficient file.

                      DECOMPRESS
                          means  that  decompression  is performed on a coeffi-
                          cient file to produce Pixel Buffers and a JPEG param-
                          eter file.

                      COLOR CONVERSION

                      NO_COLOR_CONVERT
                          produces no conversion.

                      COLOR_CONVERT
                          During compression, blocks of  pixels  are  converted
                          from  one color space to another before a DCT is per-
                          formed on them. During decompression,  the  block  of


                                      JPEG COMPRESSION/DECOMPRESSION ROUTINE  7









                          pixels that results from the inverse DCT is converted
                          from  one  color space to another before being placed
                          into the Pixel Buffer.

                      CALL SEQUENCE

                      o   Each  time  JPEG_base()  is invoked with a new image,
                          this field should be set to START_IMAGE.

                      o   JPEG_base() will then initialize various  structures,
                          including the allocation of the Pixel Buffer.

                      o   After   initialization   this   field   is   set   to
                          INTERMEDIATE_SCAN  by  JPEG_base().    On  subsequent
                          calls,  JPEG_base()  will  recognize  this and bypass
                          initialization.  The user needs to supply more  data:
                          more  pixels for compression or more coefficients for
                          decompression.

                      o   Call sequence is set to END_OF_SCAN by JPEG_base() to
                          indicate that a scan  has  been  completed,  but  the
                          entire image has not been processed. Subsequent scans
                          are yet to come.

                      o   Call  sequence  is set to END_OF_IMAGE by JPEG_base()
                          to indicate that all JPEG parameters and  image  data
                          have been processed.

                      NUMBER OF PIXEL BUFFERS

                      o   If  SINGLE_BUFFER  is specified, then only one buffer
                          is allocated for the pixels.

                      o   If  MULTIPLE_BUFFER  is  specified,   then   multiple
                          buffers  in  a  circular  chain  are  allocated.  The
                          buffers will be returned in sequence to the user  for
                          action.   In multi-tasking systems, such as OS/2, the
                          user  may   make   use   of   this   to   spawn   two
                          processes/threads, to act on the buffers in parallel.


  2.4.2.3   Color Spaces

                         These    components   are   only   relevant   if   the
                      COLOR_CONVERT flag is set.

                      o   InputColorSpace identifies the source color space.

                      o   OutputColorSpace  identifies  the  destination  color
                          space into which the source needs to be converted.

                      See  the  section  on Color Conversion below for the pos-
                      sible values of these variables.



  8  User's Guide to JPEG API for Audio Cards









  2.4.2.4   Warning and Error Parameters

                         A single unrecoverable error and any number of warning
                      messages   may  be  generated  during  the  execution  of
                      JPEG_base(). The return code from  JPEG_base()  indicates
                      which  of  the three possible situations were encountered
                      during execution:

                      0
                          Successful execution

                      1
                          Warnings were generated

                      -1
                          Unrecoverable error and possibly warnings

                      ERRORS

                         Error messages are recorded in the error structure  of
                      ComArea. The WARN_ELE structure contains:

                      MESSAGE
                          The  code  of  an  error or warning detected. See the
                          Error  and  Warning  Code  Reference  below  for  the
                          meaning of these codes.

                      DATA_VALUE
                          The value (if any) that caused the error or warning.

                      DATA_ELEMENT
                          Used  only  by the parser of the JPEG parameter file.
                          It indicates the position within the input file where
                          an error or warning was encountered.

                      WARNINGS

                      WARNING FLAGS
                          Whenever a warning is set for one of  the  categories
                          of  warnings  in the warning structure, warning_flags
                          is ORed with the corresponding  flag.  The  user  may
                          then  test  warning_flags  to  determine what kind of
                          warnings were generated.  See the ERROR  AND  WARNING
                          CODE  REFERENCE  section  below for more details. The
                          flags are:

                          o   IMAGE_FRAME_WARN

                          o   COMPONENT_WARN

                          o   SCAN

                          o   JPEG_TAB



                                      JPEG COMPRESSION/DECOMPRESSION ROUTINE  9









                          o   HUFF_TAB

                          o   QUANT_TAB

                          o   SAMPLES

                          o   DNL_WARN

                          o   PARS

                      WARNING STRUCTURE

                             The  WARN_STRUCT structure is composed of a number
                          of pointers to arrays  of  WARN_ELE  structures.  The
                          area  for  these  arrays  is allocated dynamically by
                          JPEG_base(). When  the  caller  has  completed  using
                          them,   the  user  is  responsible  for  freeing  the
                          pointers  in  WARN_STRUCT.  Each  WARN_ELE  structure
                          represents one warning condition encountered.

                             The  number  of  structures  in each array is also
                          contained in the WARN_STRUCT  structure.  Each  array
                          represents a different category of warning. The cate-
                          gories  roughly  correspond  to JPEG defined objects.
                          The categories are:

                          IMAGE/FRAME
                              Warning conditions found in Image or Frame signal
                              parameters. (Image and Frame are  interchangeable
                              for baseline JPEG.)

                          SCAN
                              Invalid scan parameters were set.

                          COMPONENT
                              Problems found with component signal parameters.

                          JPEG TABLES
                              General  problems  found in either Huffman tables
                              or Quantization tables.

                          HUFFMAN TABLES
                              Problems which  specifically  relate  to  Huffman
                              tables.

                          QUANTIZATION TABLES
                              Problems    which    specifically    relate    to
                              Quantization tables.

                          SAMPLES
                              Problems related to  sample  values  or  sampling
                              ratios.




  10  User's Guide to JPEG API for Audio Cards









                          DNL (DEFINE NUMBER OF LINES MARKER)
                              A problem with the DNL signal parameters.

                          PARSER
                              Other problems detected.



  2.4.2.5   SampleCode

                         Reserved internal variable.


  2.4.2.6   EndAreaID

                         This  is  a  pointer to a null-terminated ASCII string
                      that must be set by the caller to "ComArea". It  is  used
                      to  verify  the  integrity of the ComArea as it is passed
                      along to different functions.


  2.5   PIXEL BUFFER
  __________________



  2.5.1   STRUCTURE

                           typedef struct buffer ¤
                             BYTE far     *bufad;
                             USHORT        buflen;
                             USHORT        buflim;
                             USHORT        bufused;
                             BYTE far     *bufpt;
                             struct buffer far  *nextbuf;
                           ‡ BUFFER;


  2.5.2   DEFINITION

                      BUFAD
                          Beginning address of buffer data.

                      BUFLEN
                          Number of bytes in buffer less the  BUFFER  structure
                          size.  (The  BUFFER structure occupies the first part
                          of the buffer.)

                      BUFLIM
                          Reserved internal variable.

                      BUFUSED
                          Number of bytes already  read  from/written  to  this
                          buffer. Zero when the buffer is first allocated.



                                     JPEG COMPRESSION/DECOMPRESSION ROUTINE  11









                      BUFPT
                          Address of the last byte read or written

                      NEXTBUF
                          Address  of  the  next  buffer (if any) in a circular
                          chain of buffers. This is used  when  MULTIPLE_BUFFER
                          is specified as part of the operation.

















































  12  User's Guide to JPEG API for Audio Cards









  3.0   BUFFERING
  _______________





                         The  beginning  of  each  buffer  contains  the BUFFER
                      structure area which contains the variable values of  the
                      BUFFER  structure.  The structure area is followed by the
                      data area.  The variable bufad within the structure  area
                      contains  the  address of the beginning of the data area.
                      The variable nextbuf within the structure  area  contains
                      the address of the beginning of the next buffer, if any.


  3.1   MULTIPLE BUFFERING PROTOCOL
  _________________________________

                         When  calling  JPEG_base, the user passes a pointer of
                      type BUFFER to the routine.  If in the operation variable
                      of ComArea, the user has specified MULTIPLE_BUFFER,  mul-
                      tiple buffers, (2 or more), in a circular chain are allo-
                      cated for pixels, and the BUFFER pointer is returned with
                      the address of one of the buffers in the chain.

                         For  both Compression and Decompression, the user will
                      perform all actions on the buffer addressed by the BUFFER
                      pointer argument  of  JPEG_base.  During  each  iteration
                      cycle,  the  user  has the responsibility of ROTATING the
                      JPEG_base BUFFER pointer argument before the next call to
                      JPEG_base.  For example, if the  name  of  the  JPEG_base
                      BUFFER  pointer  argument  is PB, then ROTATION is accom-
                      plished by the statement:  "PB = PB->nextbuf".

                         There are two cases of Multiple Buffering:

                      1.  Compression

                      2.  Decompression

                      The protocol for each of these cases will be explained in
                      turn.


  3.1.1   COMPRESSION

                      1.  First Call:

                             On the first call  JPEG_base  creates  a  circular
                          chain  of buffers and returns with the BUFFER pointer
                          argument addressing one of these empty buffers.   The
                          following steps are then taken:

                          o   The user fills the buffer addressed by the BUFFER
                              pointer


                                                                  BUFFERING  13









                          o   The user ROTATES the BUFFER pointer

                          o   In two separate threads:

                              a.  The user calls JPEG_base

                              b.  The  user  begins  filling  with  pixels  the
                                  buffer addressed by the BUFFER pointer

                      2.  All Other Calls:

                             When JPEG_BASE has returned and the user has  com-
                          pleted filling the previous pixel buffer:

                          o   The user ROTATES the BUFFER pointer

                          o   In two separate threads:

                              a.  The user calls JPEG_base

                              b.  The  user  begins  filling  with  pixels  the
                                  buffer addressed by the BUFFER pointer


  3.1.2   DECOMPRESSION

                      1.  First Call

                             On the first call  JPEG_base  creates  a  circular
                          chain  of  buffers  and  fills  one with decompressed
                          pixels.  When the buffer is filled JPEG_base  returns
                          with the BUFFER pointer argument addressing the empty
                          buffer  immediately  preceding  the one that has been
                          filled. The following steps are then taken:

                          o   The user ROTATES the BUFFER pointer

                          o   In two separate threads:

                              a.  The user calls JPEG_base

                              b.  The  user  begins  using  the  pixel   buffer
                                  addressed by the BUFFER pointer

                      2.  All Other Calls

                             When  JPEG_BASE has returned and the user has com-
                          pleted using the previous pixel buffer:

                          o   The user ROTATES the BUFFER pointer

                          o   In two separate threads:

                              a.  The user calls JPEG_base


  14  User's Guide to JPEG API for Audio Cards









                              b.  The  user  begins  using  the  pixel   buffer
                                  addressed by the BUFFER pointer






















































                                                                  BUFFERING  15









  4.0   COLOR CONVERSION ROUTINE
  ______________________________





                         The API for the color conversion routine is:

                      int       ColorConvert (ComArea,
                                              InputBuffer,
                                              OutputBuffer,
                                              BufferOrRowLength,
                                              NumSamplesPerRow)

                                       COM_AREA *ComArea
                                       UCHAR    *InputBuffer
                                       UCHAR    *OutputBuffer
                                       USHORT    BufferOrRowLength
                                       USHORT    NumSamplesPerRow

                      This  routine  allows  the  user to map images among four
                      common formats:

                      RGB 888
                          (Specified as RGB888 to the color space parameters of
                          the ComArea)

                      RGB 565
                          (Specified as RGB565 for Motorola  format  or  INT565
                          for Intel format)

                      YCRCB 444
                          (Specified as YUV)

                      YCRCB 422
                          (Specified as YYUV)

                         Conversions  can  only be done between RGB 888 and any
                      one of the other three color spaces. To  convert  between
                      other  color  spaces  it is necessary to first convert to
                      RGB 888. The data used for color conversion is assumed to
                      be interleaved.

                         YUV is not byte  aligned.  This  code  uses  the  byte
                      aligned version which is denoted as YCrCb.

                         To transform from RGB to YCrCb:

                      o   Y = 0.299 R + 0.587 G + 0.114 B

                      o   U = B - Y

                      o   V = R - Y



  16  User's Guide to JPEG API for Audio Cards









                      By definition, the ISO Cr and Cb components are given by:

                      o   Cr = 0.625 V + 128

                      o   Cb = 0.5 U + 128

                         To transform the files specified from YCrCb to RGB:

                      o   U = 2 * (Cb - 128)

                      o   V = 1.6 * (Cr - 128)

                      o   R = Y + V

                      o   G = Y - 0.509 V - 0.194 U

                      o   B = Y + U

                      Note:  if  Y=0 and V/U is negative after weighting in the
                      equation for G, G will not be zero.  This will give  some
                      peculiar G outputs if U or V is pathologically wrong.


  4.1   PARAMETERS
  ________________

                         The  ComArea  was  described  under  JPEG_base().  The
                      remaining parameters are:

                      UNSIGNED CHAR FAR *INPUTBUFFER
                          The pixels to be mapped from.

                      UNSIGNED CHAR FAR *OUTPUTBUFFER
                          The pixels to be mapped to.

                      USHORT BUFFERLENGTH
                          The length of the input buffer in bytes.  The  length
                          should  be  an integer multiple of Minimum Data Units
                          of sample interleaves.   In case  one  of  the  color
                          spaces  is  YYUV,  this parameter is the length of an
                          input row of the image.  Note that the  size  of  the
                          output  buffer  depends  on  which  color  spaces are
                          involved. RGB 888 needs 1.5 * (RGB565/INT565 or  YYUV
                          buffer  size).  RGB  888 and YUV need the same buffer
                          sizes.

                      USHORT NUMSAMPLESPERROW
                          If neither of the color spaces is YYUV, then this  is
                          a  "don't  care" parameter.   Otherwise, this parame-
                          ter's value is the number of samples in a row of  the
                          component  with  the  maximum  number  of  horizontal
                          samples.





                                                   COLOR CONVERSION ROUTINE  17









  5.0   COLOR SPACE CONVERSION PROGRAM: COLORCON.EXE
  __________________________________________________





                         The  COLORCON  utility  converts  a file of pixel data
                      from one color space to another. The program is called as
                      follows:

                           COLORCON /i Input_File_Name
                                    /o Output_File_Name
                                    /r <Number of Samples Per Row>
                                    /c <From Space> <To Space>

                      Possible values of <From Space> and <To Space>:

                      o   RGB888

                      o   YUV

                      o   YYUV

                      o   RGB565/INT565

                      Note that color conversions  can  only  be  done  between
                      RGB888 and one of the other three color spaces.





























  18  User's Guide to JPEG API for Audio Cards









  6.0   ERROR AND WARNING CODES REFERENCE
  _______________________________________







  6.1   ERRORS
  ____________



  6.1.1   EXTERNAL ERRORS

                         The  following  errors  are  defined in JPEGERR.H. The
                      error number will be placed in the message element of the
                      error structure within the  ComArea  structure.    Unless
                      otherwise  noted,  the  data  element  with  a problem is
                      reported in the data_element variable of the error struc-
                      ture. The  value  causing  the  problem  is  reported  in
                      data_value.



































                                          ERROR AND WARNING CODES REFERENCE  19









                      +---------------------------+---------------------------+
                      | NAME                      | DEFINITION                |
                      +---------------------------+---------------------------+
                      | READ_INVALID              | Error reading a JPEG      |
                      |                           | parameter file or Coeffi- |
                      |                           | cient file. data_value    |
                      |                           | has the error returned by |
                      |                           | the C read() function.    |
                      |                           | data_element has the      |
                      |                           | number of bytes read.     |
                      +---------------------------+---------------------------+
                      | WRITE_INVALID             | Error writing the Coeffi- |
                      |                           | cient file. data_value    |
                      |                           | has the error returned by |
                      |                           | the C write() function.   |
                      |                           | data_element has the      |
                      |                           | number of bytes written.  |
                      +---------------------------+---------------------------+
                      | ACPA_INIT_DEV_DRV         | M-ACPA device driver not  |
                      |                           | found.                    |
                      +---------------------------+---------------------------+
                      | ACPA_INIT_CARD_NOT_FOUND  | M-ACPA card not found.    |
                      +---------------------------+---------------------------+
                      | ACPA_INIT_CARD_LOCKED     |                           |
                      | Another process is using  |                           |
                      | the M-ACPA card.          |                           |
                      +---------------------------+---------------------------+
                      | ACPA_INIT_UNRECOGNIZED    | Error return from M-ACPA  |
                      | _ERROR                    | init not recognized. The  |
                      |                           | return code from the card |
                      |                           | is reported in the        |
                      |                           | data_value element of the |
                      |                           | error structure.          |
                      +---------------------------+---------------------------+
                      | BUF_PIXEL_ALLOC           | Unable to allocate pixel  |
                      |                           | buffer. data_element and  |
                      |                           | data_value are not used.  |
                      +---------------------------+---------------------------+
                      | BUF_NON_PIXEL_ALLOC       | Unable to allocate non-   |
                      |                           | pixel buffer.             |
                      |                           | data_element and          |
                      |                           | data_value are not used.  |
                      +---------------------------+---------------------------+
                      | RESTART_INTERVAL_INVALID  | Restart interval is not   |
                      |                           | an integer number of      |
                      |                           | Minimum Data Units (MDU)  |
                      |                           | per line. Actual number   |
                      |                           | is in data_value. MDU per |
                      |                           | line is in data_element.  |
                      +---------------------------+---------------------------+






  20  User's Guide to JPEG API for Audio Cards









                      +---------------------------+---------------------------+
                      | QUANT_TAB_INDEX_INVALID   | Quantization table out of |
                      |                           | range. The table index is |
                      |                           | reported in data_value.   |
                      |                           | data_element contains the |
                      |                           | element number causing    |
                      |                           | the problem.              |
                      +---------------------------+---------------------------+
                      | MDU_TO_CODE_0             | Specified number of MDU   |
                      |                           | to code is 0. At least    |
                      |                           | one is required.          |
                      |                           | data_element and          |
                      |                           | data_value are not used.  |
                      +---------------------------+---------------------------+
                      | HUFF_COEFF_SIZE_16        | The coefficient size was  |
                      |                           | 16. data_element and      |
                      |                           | data_value are not used.  |
                      +---------------------------+---------------------------+
                      | PARS_STACK_OVFLW          | The stack of the JPEG     |
                      |                           | parameter file parser     |
                      |                           | overflowed at the byte    |
                      |                           | number stored in          |
                      |                           | data_element. data_value  |
                      |                           | is not used.              |
                      +---------------------------+---------------------------+
                      | PARS_JPEG_HDR_SYNTAX      | A syntax error was found  |
                      |                           | in the JPEG parameter     |
                      |                           | file at the byte number   |
                      |                           | stored in data_element.   |
                      |                           | data_value is not used.   |
                      +---------------------------+---------------------------+
                      | PARS_LINE_LENGTH_0        | Image line length must be |
                      |                           | greater than 0.           |
                      +---------------------------+---------------------------+
                      | PARS_NUM_LINES_NOT_GEN    | Number of lines must be   |
                      |                           | set either by frame       |
                      |                           | parameters or by DNL at   |
                      |                           | end of first scan.        |
                      +---------------------------+---------------------------+
                      | PARS_IMAGE_NULL           | The image file is null.   |
                      |                           | data_value is not used.   |
                      +---------------------------+---------------------------+
                      | PARS_IMAGE_DATA_ORDER     | Data is in the wrong      |
                      |                           | order. data_value is not  |
                      |                           | used.                     |
                      +---------------------------+---------------------------+
                      | PARS_COM_AREA_OPERATION   | Invalid operation speci-  |
                      | _INVALID                  | fied in the ComArea.      |
                      |                           | data_value contains oper- |
                      |                           | ation.  data_element is   |
                      |                           | not used.                 |
                      +---------------------------+---------------------------+




                                          ERROR AND WARNING CODES REFERENCE  21









                      +---------------------------+---------------------------+
                      | COLOR_CON_SPACE_INVALID   | Selected color space is   |
                      |                           | invalid. Conversion can   |
                      |                           | only be done to/from      |
                      |                           | RGB888 and another color  |
                      |                           | space. data_value con-    |
                      |                           | tains the invalid color   |
                      |                           | space selected.           |
                      |                           | data_element is not used. |
                      +---------------------------+---------------------------+
                      | HUFF_TAB_RESYNC           | Overlapping resync in     |
                      |                           | Huffman table.            |
                      +---------------------------+---------------------------+
                      | HUFF_TAB_ZERO_NUM         | Invalid Huffman table.    |
                      |                           | There were no code        |
                      |                           | lengths less than or      |
                      |                           | equal to 8.               |
                      +---------------------------+---------------------------+
                      | OUT_OF_MEMORY             | There is not enough       |
                      |                           | memory to complete the    |
                      |                           | process. Requested size   |
                      |                           | is in data_value.         |
                      +---------------------------+---------------------------+


  6.1.2   INTERNAL ERRORS

                         The  following  errors  indicate a problem internal to
                      the JPEG_base() routine.  Please contact your IBM  repre-
                      sentative for assistance.


























  22  User's Guide to JPEG API for Audio Cards









                      +---------------------------+---------------------------+
                      | NAME                      | DEFINITION                |
                      +---------------------------+---------------------------+
                      | OUT_OF_RANGE_IMAGE_FRAME  | An undefined image frame  |
                      | _WARN                     | warning occurred. The     |
                      |                           | ComArea is probably       |
                      |                           | corrupt.                  |
                      +---------------------------+---------------------------+
                      | OUT_OF_RANGE_COMPONENT    | An undefined component    |
                      | _WARN                     | warning occurred. The     |
                      |                           | ComArea is probably       |
                      |                           | corrupt.                  |
                      +---------------------------+---------------------------+
                      | OUT_OF_RANGE_SAMPLES      | An undefined samples      |
                      | _WARN                     | warning occurred. The     |
                      |                           | ComArea is probably       |
                      |                           | corrupt.                  |
                      +---------------------------+---------------------------+
                      | OUT_OF_RANGE_SCAN_WARN    | An undefined scan warning |
                      |                           | occurred. The ComArea is  |
                      |                           | probably corrupt.         |
                      +---------------------------+---------------------------+
                      | OUT_OF_RANGE_JPEG_TABLE   | An undefined JPEG table   |
                      | _WARN                     | warning occurred. The     |
                      |                           | ComArea is probably       |
                      |                           | corrupt.                  |
                      +---------------------------+---------------------------+
                      | OUT_OF_RANGE_HUFF_TABLE   | An undefined Huffman      |
                      | _WARN                     | table warning occurred.   |
                      |                           | The ComArea is probably   |
                      |                           | corrupt.                  |
                      +---------------------------+---------------------------+
                      | OUT_OF_RANGE_QUANT_TABLE  | An undefined quant. table |
                      | _WARN                     | warning occurred. The     |
                      |                           | ComArea is probably       |
                      |                           | corrupt.                  |
                      +---------------------------+---------------------------+
                      | OUT_OF_RANGE_DNL_WARN     | An undefined DNL warning  |
                      |                           | occurred. The ComArea is  |
                      |                           | probably corrupt.         |
                      +---------------------------+---------------------------+
                      | OUT_OF_RANGE_PARS_WARN    | An undefined parser       |
                      |                           | warning occurred. The     |
                      |                           | ComArea is probably       |
                      |                           | corrupt.                  |
                      +---------------------------+---------------------------+
                      | OUT_OF_RANGE_WARN         | An undefined warning cat- |
                      |                           | egory occurred. The       |
                      |                           | ComArea is probably       |
                      |                           | corrupt.                  |
                      +---------------------------+---------------------------+





                                          ERROR AND WARNING CODES REFERENCE  23









                      +---------------------------+---------------------------+
                      | BUF_NUM_LINES_NOT_INTEGER | Number of lines in the    |
                      | _MULT                     | pixel buffer not an       |
                      |                           | integer multiple of 8.    |
                      |                           | data_value contains the   |
                      |                           | number of lines.          |
                      |                           | data_element is not used. |
                      +---------------------------+---------------------------+
                      | BUF_OUT_OF_BOUNDS_ADDR    | The buffer location being |
                      |                           | addressed is outside the  |
                      |                           | limits of the buffer.     |
                      |                           | data_value contains the   |
                      |                           | location accessed.        |
                      |                           | data_element contains the |
                      |                           | last legal location.      |
                      +---------------------------+---------------------------+
                      | BUF_UNPUTBYTE             | Unable to remove a byte   |
                      |                           | from a buffer.            |
                      +---------------------------+---------------------------+
                      | BUF_INPUT_SIZE            | Invalid input buffer      |
                      |                           | size. The pixel buffer is |
                      |                           | not large enough to       |
                      |                           | contain an integer number |
                      |                           | of pixel lines.           |
                      |                           | data_value contains the   |
                      |                           | buffer length.            |
                      |                           | data_element contains the |
                      |                           | number of bytes per line. |
                      +---------------------------+---------------------------+
                      | QUANT_TBL_PTR_NULL        | The pointer to the        |
                      |                           | quantization table was    |
                      |                           | null during the proc-     |
                      |                           | essing of the frame       |
                      |                           | segment parameters.       |
                      |                           | data_value contains the   |
                      |                           | component ID.             |
                      +---------------------------+---------------------------+
                      | HUF_DC_TBL_PTR_NULL       | The pointer to the        |
                      |                           | Huffman DC table was null |
                      |                           | during the processing of  |
                      |                           | the scan segment parame-  |
                      |                           | ters. data_value contains |
                      |                           | the component ID.         |
                      +---------------------------+---------------------------+
                      | HUF_AC_TBL_PTR_NULL       | The pointer to the        |
                      |                           | Huffman AC table was null |
                      |                           | during the processing of  |
                      |                           | the scan segment parame-  |
                      |                           | ters. data_value contains |
                      |                           | the component ID.         |
                      +---------------------------+---------------------------+





  24  User's Guide to JPEG API for Audio Cards









  6.2  WARNINGS
  _____________

                         A warning does not prevent JPEG_base() from continuing
                      its  processing.  However,  results may be unpredictable.
                      Processing of the input file can continue to  find  other
                      possible problems with the data. Multiple warnings can be
                      reported  as  a  result  of  running  JPEG_base(). When a
                      warning occurs, a bit is turned on in  the  warning_flags
                      element  of the ComArea structure. The user can determine
                      what type of warnings were encountered by examining which
                      flags were turned on. The following bit masks  have  been
                      defined  in  JPEGERR.H.  They can be logically ANDed with
                      warning_flags to determine which flags are set.

                      +---------------------------+---------------------------+
                      | NAME                      | DEFINITION                |
                      +---------------------------+---------------------------+
                      | IMAGE_FRAME_WARN          | An image frame warning    |
                      |                           | occurred                  |
                      +---------------------------+---------------------------+
                      | COMPONENT                 | A component related       |
                      |                           | warning occurred          |
                      +---------------------------+---------------------------+
                      | SAMPLES                   | A sampling related        |
                      |                           | warning occurred          |
                      +---------------------------+---------------------------+
                      | SCAN                      | A scanning related        |
                      |                           | warning occurred          |
                      +---------------------------+---------------------------+
                      | JPEG_TAB                  | A table allocation        |
                      |                           | warning occurred          |
                      +---------------------------+---------------------------+
                      | HUFF_TAB                  | A Huffman table warning   |
                      |                           | occurred                  |
                      +---------------------------+---------------------------+
                      | QUANT_TAB                 | A quantization table      |
                      |                           | warning occurred          |
                      +---------------------------+---------------------------+
                      | DNL_WARN                  | A DNL warning occurred    |
                      +---------------------------+---------------------------+
                      | PARS                      | A data warning occurred   |
                      |                           | parsing the JPEG param-   |
                      |                           | eter file                 |
                      +---------------------------+---------------------------+

                         The  WARN_STRUCT  element  of  the  ComArea   contains
                      pointers to the different categories of structures, along
                      with  variables  that  indicate how many warnings of each
                      category occurred.

                         Unless  otherwise  noted,  the  data  element  with  a
                      problem  is  reported in the data_element variable of the
                      corresponding warning structure. The  value  causing  the
                      problem  is reported in data_value. The warning number is


                                          ERROR AND WARNING CODES REFERENCE  25









                      reported in the message element of the individual warning
                      structure.  The  following  warnings   are   defined   in
                      JPEGERR.H.


  6.2.1   THE FOLLOWING WARNINGS SET THE IMAGE_FRAME_WARN FLAG:

                      +---------------------------+---------------------------+
                      | NAME                      | DEFINITION                |
                      +---------------------------+---------------------------+
                      | IMAGE_FRAME_PRECISION     | Precision must be 8 for   |
                      |                           | baseline system.          |
                      +---------------------------+---------------------------+
                      | IMAGE_FRAME_COMP          | Number of frame compo-    |
                      |                           | nents must be greater     |
                      |                           | than 0.                   |
                      +---------------------------+---------------------------+
                      | IMAGE_FRAME_SOF_INVALID   | Start of Frame marker is  |
                      |                           | not valid. Only SOF0      |
                      |                           | (0xC0) is valid for a     |
                      |                           | baseline system. The      |
                      |                           | actual value found is     |
                      |                           | reported in data_value.   |
                      +---------------------------+---------------------------+


  6.2.2   THE FOLLOWING WARNINGS SET THE COMPONENT FLAG:

                      +---------------------------+---------------------------+
                      | NAME                      | DEFINITION                |
                      +---------------------------+---------------------------+
                      | COMP_ID_DEF               | Component ID from scan    |
                      |                           | segment not found in      |
                      |                           | frame segment. data_value |
                      |                           | not used.                 |
                      +---------------------------+---------------------------+
                      | COMP_CNT                  | Number of components must |
                      |                           | be between 1 and 4.       |
                      +---------------------------+---------------------------+


  6.2.3   THE FOLLOWING WARNINGS SET THE SCAN FLAG:














  26  User's Guide to JPEG API for Audio Cards









                      +---------------------------+---------------------------+
                      | NAME                      | DEFINITION                |
                      +---------------------------+---------------------------+
                      | SCAN_START_OF_SPECTRAL    | Start of spectral         |
                      |                           | selection must be 0 for   |
                      |                           | baseline system.          |
                      +---------------------------+---------------------------+
                      | SCAN_END_OF_SPECTRAL      | End of spectral selection |
                      |                           | must be 63 for baseline   |
                      |                           | system.                   |
                      +---------------------------+---------------------------+
                      | SCAN_SUCCESSIVE_APPROX    | Successive approximation  |
                      |                           | must be 0 for baseline    |
                      |                           | system.                   |
                      +---------------------------+---------------------------+


  6.2.4   THE FOLLOWING WARNINGS SET THE JPEG_TAB FLAG:

                      +---------------------------+---------------------------+
                      | NAME                      | DEFINITION                |
                      +---------------------------+---------------------------+
                      | JPEG_TABLE_ALLOC          | JPEG tables not allocated |
                      |                           | in Define Quantization    |
                      |                           | Table (DQT marker).       |
                      |                           | data_value not used.      |
                      +---------------------------+---------------------------+


  6.2.5   THE FOLLOWING WARNINGS SET THE HUFF_TAB FLAG:


























                                          ERROR AND WARNING CODES REFERENCE  27









                      +---------------------------+---------------------------+
                      | NAME                      | DEFINITION                |
                      +---------------------------+---------------------------+
                      | HUFF_DUPLICATE            | Duplication error.        |
                      |                           | data_value and            |
                      |                           | data_element not used.    |
                      +---------------------------+---------------------------+
                      | HUFF_TAB_SETUP            | Failure in Huffman table  |
                      |                           | setup. Some of the        |
                      |                           | entries were not set up.  |
                      |                           | data_value contains the   |
                      |                           | index of the first entry  |
                      |                           | that was not set up.      |
                      +---------------------------+---------------------------+
                      | HUFF_LENGTH               | Huffman table length      |
                      |                           | error. The actual table   |
                      |                           | length does not match the |
                      |                           | length specified by the   |
                      |                           | DHT marker.               |
                      +---------------------------+---------------------------+
                      | HUFF_DC_ID_RANGE          | DC table ID out of range  |
                      |                           | for baseline system. Must |
                      |                           | be 0x00 or 0x01.          |
                      +---------------------------+---------------------------+
                      | HUFF_AC_ID_RANGE          | AC table ID out of range  |
                      |                           | for baseline system. Must |
                      |                           | be 0x10 or or 0x11 in the |
                      |                           | DHT segment, and 0 or 1   |
                      |                           | in the scan segment.      |
                      +---------------------------+---------------------------+
                      | HUFF_DC_LUM_TABLE         | DC luminance table ID out |
                      |                           | of range.  Must be 0x00   |
                      |                           | or 0x01.                  |
                      +---------------------------+---------------------------+
                      | HUFF_DC_CHROM_TABLE DC    | Chrominance table ID out  |
                      |                           | of range.  Must be 0x00   |
                      |                           | or 0x01.                  |
                      +---------------------------+---------------------------+
                      | HUFF_AC_LUM_TABLE AC      | luminance table ID out of |
                      |                           | range. Must be 0x10 or or |
                      |                           | 0x11 in the DHT segment,  |
                      |                           | and 0 or 1 in the scan    |
                      |                           | segment.                  |
                      +---------------------------+---------------------------+
                      | HUFF_AC_CHROM_TABLE       | AC chrominance table ID   |
                      |                           | out of range. Must be     |
                      |                           | 0x10 or or 0x11 in the    |
                      |                           | DHT segment, and 0 or 1   |
                      |                           | in the scan segment.      |
                      +---------------------------+---------------------------+






  28  User's Guide to JPEG API for Audio Cards









  6.2.6   THE FOLLOWING WARNINGS SET THE QUANT_TAB FLAG:

                      +---------------------------+---------------------------+
                      | NAME                      | DEFINITION                |
                      +---------------------------+---------------------------+
                      | QUANT_TABLE_DQT_ID_RANGE  | Quantization table ID out |
                      |                           | of range for baseline     |
                      |                           | system. Must be between 0 |
                      |                           | and 3.                    |
                      +---------------------------+---------------------------+


  6.2.7   THE FOLLOWING WARNINGS SET THE SAMPLES FLAG:

                      +---------------------------+---------------------------+
                      | NAME                      | DEFINITION                |
                      +---------------------------+---------------------------+
                      | SAMPLES_HOR_RANGE         | Horizontal Sample out of  |
                      |                           | range. Must be 1 to 4.    |
                      +---------------------------+---------------------------+
                      | SAMPLES_VERT_RANGE        | Vertical Sample out of    |
                      |                           | range. Must be 1 to 4.    |
                      +---------------------------+---------------------------+
                      | SAMPLES_PER_MDU           | Number of samples per MDU |
                      |                           | greater than 10.          |
                      +---------------------------+---------------------------+


  6.2.8   THE FOLLOWING WARNINGS SET THE DNL_WARN FLAG:

                      +---------------------------+---------------------------+
                      | NAME                      | DEFINITION                |
                      +---------------------------+---------------------------+
                      | DNL_INVALID               | The DNL segment length    |
                      |                           | was not 4. data_value     |
                      |                           | contains the invalid      |
                      |                           | length.                   |
                      +---------------------------+---------------------------+


  6.2.9   THE FOLLOWING WARNINGS SET THE PARS FLAG:

                      +---------------------------+---------------------------+
                      | NAME                      | DEFINITION                |
                      +---------------------------+---------------------------+
                      | PARS_INVALID              | Invalid marker code in    |
                      |                           | data.                     |
                      +---------------------------+---------------------------+
                      | PARS_ZERO_INVALID         | Invalid data following    |
                      |                           | zero token                |
                      +---------------------------+---------------------------+





                                          ERROR AND WARNING CODES REFERENCE  29









  7.0   JPEG PARAMETER MANIPULATION PROGRAMS: SETPARAM AND GETPARAM
  _________________________________________________________________





                         The  following  programs allow the user to examine and
                      modify  a  JPEG  parameter  file.  The  SETPARAM  utility
                      changes  a  JPEG  parameter  file.  The  GETPARAM utility
                      reports the values of signal parameters.  Both  utilities
                      take  an  input file and generate an output file based on
                      the action specified. Input and output files can  be  the
                      same  file. A variable number of parameters is associated
                      with each action.


  7.1   SETPARAM UTILITY
  ______________________

                         The SETPARAM utility changes the information in a JPEG
                      parameter file and writes out a new file with the changed
                      information. The program is called as follows:

                      o   SETPARAM   Input_File_Name Output_File_Name  <action>
                          <Variable Parameters>


  7.1.1   POSSIBLE VALUES OF <ACTION>:





























  30  User's Guide to JPEG API for Audio Cards









                      +---------------------------+---------------------------+
                      | <ACTION> NAME             | <ACTION> DEFINITION       |
                      +---------------------------+---------------------------+
                      | size                      | change either the width   |
                      |                           | (number of pixels per     |
                      |                           | line) or height (number   |
                      |                           | of lines) of the image.   |
                      +---------------------------+---------------------------+
                      | huff                      | change either <ac> or     |
                      |                           | <dc> Huffman table        |
                      |                           | <index> associated with   |
                      |                           | component <c> in scan     |
                      |                           | <s>. An error is reported |
                      |                           | if scan <s> does not      |
                      |                           | exist, or the Huffman     |
                      |                           | table <index> is not one  |
                      |                           | allowed by the JPEG       |
                      |                           | Baseline Standard.        |
                      +---------------------------+---------------------------+
                      | quant                     | change quantization table |
                      |                           | associated with component |
                      |                           | <c> to <index>. An        |
                      |                           | optional filename can be  |
                      |                           | specified. This ASCII     |
                      |                           | file should contain 64    |
                      |                           | values to replace the 64  |
                      |                           | elements of the selected  |
                      |                           | quantization table. The   |
                      |                           | values are separated by   |
                      |                           | blanks. If a DQT segment  |
                      |                           | for quantization table    |
                      |                           | <index> does not exist,   |
                      |                           | an error is reported.     |
                      +---------------------------+---------------------------+
                      | samp                      | change the sampling ratio |
                      |                           | to either YUV or YYUV.    |
                      +---------------------------+---------------------------+
                      | restart                   | change the restart        |
                      |                           | interval to <r>.  If no   |
                      |                           | DRI segment exists, then  |
                      |                           | no action is taken.       |
                      +---------------------------+---------------------------+














                JPEG PARAMETER MANIPULATION PROGRAMS: SETPARAM AND GETPARAM  31









                      +---------------------------+---------------------------+
                      | scan                      | modify or add a scan      |
                      |                           | segment:                  |
                      |                           |                           |
                      |                           | o   If the scan segment   |
                      |                           |     exists and the number |
                      |                           |     of components and     |
                      |                           |     component IDs match   |
                      |                           |     the existing segment, |
                      |                           |     then the segment      |
                      |                           |     table id's are modi-  |
                      |                           |     fied if they are      |
                      |                           |     legal JPEG Baseline   |
                      |                           |     Huffman indices.  An  |
                      |                           |     error is reported if  |
                      |                           |     the indices do not    |
                      |                           |     meet the standard.    |
                      |                           |                           |
                      |                           | o   If the segment exists |
                      |                           |     but NumComponents is  |
                      |                           |     0, the segment is     |
                      |                           |     deleted.              |
                      |                           |                           |
                      |                           | o   If the segment exists |
                      |                           |     but there is no exact |
                      |                           |     match of components   |
                      |                           |     IDs, the information  |
                      |                           |     specified is inserted |
                      |                           |     as a new scan segment |
                      |                           |     after the matching    |
                      |                           |     scan segment.         |
                      |                           |                           |
                      |                           | o   If the scan does not  |
                      |                           |     exist, the informa-   |
                      |                           |     tion is added imme-   |
                      |                           |     diately before the    |
                      |                           |     EOI marker in the     |
                      |                           |     JPEG parameter file.  |
                      +---------------------------+---------------------------+


  7.1.2   ACTIONS AND VARIABLE PARAMETERS:














  32  User's Guide to JPEG API for Audio Cards









                      +---------------------------+---------------------------+
                      | <ACTION>                  | PARAMETERS                |
                      +---------------------------+---------------------------+
                      | size                      | /w# /h#    (either one or |
                      |                           | both /w and /h may be     |
                      +---------------------------+---------------------------+
                      | huff                      | /s# [ /ac | /dc ] /i# /c# |
                      +---------------------------+---------------------------+
                      | quant                     | /i# /c#  optional:        |
                      |                           | Quant_File_Name           |
                      +---------------------------+---------------------------+
                      | samp                      | [ /RGB | /YUV | /YYUV ]   |
                      +---------------------------+---------------------------+
                      | restart                   | #                         |
                      +---------------------------+---------------------------+
                      | scan                      | /s# NumComponents ¤       |
                      |                           | ComponentID DCTblIndex    |
                      |                           | ACTblIndex ‡              |
                      +---------------------------+---------------------------+


  7.2   GETPARAM UTILITY
  ______________________

                         The GETPARAM examines a JPEG parameter file and writes
                      out  the information to a text file. The fixed parameters
                      are the same as for SETPARAM  with  the  addition  of  an
                      "all"  action  which  causes  all of the parameters to be
                      reported.  Except for scan actions, nothing  is  reported
                      if the information requested does not exist.  The program
                      is called as follows:

                      o   GETPARAM    Input_File_Name Output_File_Name <action>
                          <Variable Parameters>


  7.2.1   ACTIONS, VARIABLE PARAMETERS AND THE RESPONSE OF GETPARAM:




















                JPEG PARAMETER MANIPULATION PROGRAMS: SETPARAM AND GETPARAM  33









                      +---------------------------+---------------------------+
                      | <ACTION>                  | PARAMETERS                |
                      +---------------------------+---------------------------+
                      | size                      | none -- reports the       |
                      |                           | height and width of the   |
                      |                           | image.                    |
                      +---------------------------+---------------------------+
                      | huff                      | /s# [ ac | dc ] [ /i# |   |
                      |                           | /c# ] -- Reports the      |
                      |                           | association of Huffman    |
                      |                           | table i to component c    |
                      |                           | (or vice versa) for scan  |
                      |                           | s.  No action is taken if |
                      |                           | the scan or component do  |
                      |                           | not exist.  If the "all"  |
                      |                           | action is specified, then |
                      |                           | all Huffman i, c associ-  |
                      |                           | ations are reported for   |
                      |                           | all scan segments.        |
                      +---------------------------+---------------------------+
                      | quant                     | [ /i# | /c# ] -- Reports  |
                      |                           | the association of        |
                      |                           | quantization table i to   |
                      |                           | component c or vice versa |
                      |                           | and the 64 values of the  |
                      |                           | table. If the             |
                      |                           | quantization table or     |
                      |                           | component do not exist,   |
                      |                           | then nothing is reported. |
                      |                           | If "all" is specified,    |
                      |                           | then all Quantization     |
                      |                           | table, component ID asso- |
                      |                           | ciations, and the con-    |
                      |                           | tents of Quantization     |
                      |                           | tables are reported.      |
                      +---------------------------+---------------------------+
                      | samp                      | none -- Reports the sam-  |
                      |                           | pling ratios for all com- |
                      |                           | ponents.                  |
                      +---------------------------+---------------------------+
                      | restart                   | none -- Reports the       |
                      |                           | restart interval value,   |
                      |                           | or 0 if no restart inter- |
                      |                           | vals are defined.         |
                      +---------------------------+---------------------------+











  34  User's Guide to JPEG API for Audio Cards









                      +---------------------------+---------------------------+
                      | scan                      | /s# -- Reports the number |
                      |                           | of components in scan #.  |
                      |                           | For each component in the |
                      |                           | scan segment, the Compo-  |
                      |                           | nent ID and its associ-   |
                      |                           | ated DC and AC Huffman    |
                      |                           | table indices are         |
                      |                           | reported. If the scan     |
                      |                           | segment does not exist,   |
                      |                           | then a message to this    |
                      |                           | effect is written.        |
                      +---------------------------+---------------------------+
                      | all                       | none -- Reports all of    |
                      |                           | the above.                |
                      +---------------------------+---------------------------+








































                JPEG PARAMETER MANIPULATION PROGRAMS: SETPARAM AND GETPARAM  35









  8.0   DEPENDENCIES
  __________________







  8.1   HARDWARE
  ______________

                      o   IBM PS/2 with M-Audio Capture and Playback Adapter


  8.2   SOFTWARE
  ______________

                      o   IBM Operating System/2  Version 1.3 or

                      o   IBM DOS 4.0 (with optional Microsoft Windows 3.0)

                      o   M-ACPA device driver for IBM OS/2 or IBM DOS

                      o   Microsoft Windows Software Development Kit to develop
                          Windows applications.

                      o   IBM OS/2 Programming Tools and Information to develop
                          OS/2 applications.






























  36  User's Guide to JPEG API for Audio Cards









  9.0   SUBDIRECTORY CONTENTS
  ___________________________





                      +---------------------------+---------------------------+
                      | FILE NAME                 | DESCRIPTION               |
                      +---------------------------+---------------------------+
                      | README                    | This documentation file   |
                      +---------------------------+---------------------------+
                      | JPEGOS2.DLL               | OS/2 Dynamic Link Library |
                      +---------------------------+---------------------------+
                      | JPEGOS2.LIB               | OS/2 import library       |
                      +---------------------------+---------------------------+
                      | JPEGWIN.DLL               | Microsoft Windows 3.0 DLL |
                      +---------------------------+---------------------------+
                      | JPEGWIN.LIB               | MS Windows import library |
                      +---------------------------+---------------------------+
                      | JPEGDOS.LIB               | DOS library file to be    |
                      |                           | linked in by DOS applica- |
                      |                           | tions                     |
                      +---------------------------+---------------------------+
                      | GETPARAM.EXE,             | Utilities to examine and  |
                      | SETPARAM.EXE              | change JPEG parameter     |
                      |                           | files                     |
                      +---------------------------+---------------------------+
                      | COLORCON.EXE              | Utility to do color space |
                      |                           | conversion                |
                      +---------------------------+---------------------------+
                      | SAMPOS2.EXE, SAMPDOS.EXE, | Sample programs for OS/2  |
                      | SAMPWIN.EXE               | , DOS and Microsoft       |
                      |                           | Windows 3.0. Enter        |
                      |                           | PROGNAME ?  for help      |
                      |                           | (e.g. SAMPOS2 ?)          |
                      +---------------------------+---------------------------+


  9.1   JPEG\SOURCE SUBDIRECTORY WITH SAMPLE SOURCE CODE
  ______________________________________________________

















                                                      SUBDIRECTORY CONTENTS  37









                      +---------------------------+---------------------------+
                      | FILE NAME                 | DESCRIPTION               |
                      +---------------------------+---------------------------+
                      | JPEG.H                    | General C definitions     |
                      +---------------------------+---------------------------+
                      | JPEGERR.H                 | Error structure defi-     |
                      |                           | nitions                   |
                      +---------------------------+---------------------------+
                      | SAMPLE.C                  | Sample C source code      |
                      +---------------------------+---------------------------+
                      | WINSAMP.C                 | Sample C source code for  |
                      |                           | MS Windows                |
                      +---------------------------+---------------------------+
                      | WINSAMP.H                 | Include file              |
                      +---------------------------+---------------------------+
                      | SAMPWIN.RC                | Resource file             |
                      +---------------------------+---------------------------+
                      | SAMPWIN.DEF               | Module Definition File    |
                      +---------------------------+---------------------------+
                      | SAMPOS2.MAK               | Make file for OS/2 exe-   |
                      |                           | cutable                   |
                      +---------------------------+---------------------------+
                      | SAMPDOS.MAK               | Make file for DOS execut- |
                      |                           | able                      |
                      +---------------------------+---------------------------+
                      | SAMPWIN.MAK               | Make file for MS WINDOWS  |
                      |                           | executable                |
                      +---------------------------+---------------------------+
                      | JPEGx.HDR                 | Sample JPEG parameter     |
                      |                           | file with x components. x |
                      |                           | is between 1 and 4.       |
                      |                           | JPEG1.HDR is used for     |
                      |                           | monochrome images.        |
                      +---------------------------+---------------------------+
                      | BEARRGB.DCT               | Sample compressed image - |
                      |                           | RGB format                |
                      +---------------------------+---------------------------+



















  38  User's Guide to JPEG API for Audio Cards









  10.0   LIMITATIONS
  __________________





                         This  API  has been optimized for interleaved data for
                      RGB, YUV, YYUV and Y (monochrome) images.  Other  formats
                      will  take  longer  to  compress  and decompress than the
                      optimized formats.










































                                                                LIMITATIONS  39





