clAddAlgorithm(3dm)                                        clAddAlgorithm(3dm)


NAME
     clAddAlgorithm, clSetUnique, clGetUnique, clFetchParam, clStoreParam,
     clError - Add a video or audio compression algorithm to the Compression
     Library

SYNOPSIS
     #include <dmedia/cl.h>

     int clAddAlgorithm(char *name, int algType, int maxHeaderSize,
         FunctionPtr openCompressor, FunctionPtr compress,
         FunctionPtr closeCompressor,
         FunctionPtr openDecompressor, FunctionPtr decompress,
         FunctionPtr closeDecompressor,
         FunctionPtr readHeader, FunctionPtr queryScheme,
         FunctionPtr queryLicense,
         FunctionPtr getParams, FunctionPtr setParams,
         int *scheme)

     void *clSetUnique(CLhandle handle, void *unique)
     void *clGetUnique(CLhandle handle)

     int  clFetchParam(CLhandle handle, int paramID)
     void clStoreParam(CLhandle handle, int paramID, int value)

     void clError(CLhandle handle, int code, const char *format, ...)


ARGUMENTS
     name           A pointer to a string that contains the name of the
                    algorithm.

     algType        The type of the algorithm (CL_ALG_VIDEO or CL_ALG_AUDIO).

     maxHeaderSize  The maximum size of the stream header for the specified
                    algorithm.

     openCompressor A pointer to the function that opens a compressor for the
                    new algorithm.  The function must have the same arguments
                    as clOpenCompressor.

     compress       A pointer to the function that compresses for the new
                    algorithm.  The function must have the same arguments as
                    clCompress.

     closeCompressor
                    A pointer to the function that closes a compressor for the
                    new algorithm.  The function must have the same arguments
                    as clCloseCompressor.

     openDecompressor
                    A pointer to the function that opens a decompressor for
                    the new algorithm.  The function must have the same


                    arguments as clOpenDecompressor.

     decompress     A pointer to the function that decompresses for the new
                    algorithm.  The function must have the same arguments as
                    clDecompress.

     closeDecompressor
                    A pointer to the function that closes a decompressor for
                    the new algorithm.  The function must have the same
                    arguments as clCloseDecompressor.

     readHeader     A pointer to the function that reads the stream header for
                    the new algorithm. The function must have the same
                    arguments as clReadHeader.

     queryScheme    A pointer to the function that identifies the scheme from
                    the stream header for the new algorithm. The function must
                    have the same arguments as clQueryScheme.

     queryLicense   A pointer to the function that checks for a NetLS license.
                    The function must have the same arguments as
                    clQueryLicense.

     getParams      A pointer to the function that gets
                    compressor/decompressor parameters for the new algorithm.
                    The function must have the same arguments as clGetParams.

     setParams      A pointer to the function that sets
                    compressor/decompressor parameters for the new algorithm.
                    The function must have the same arguments as clSetParams.

     scheme         A pointer to an int value to receive the compression
                    scheme identifier.

     handle         A handle to a compressor/decompressor.

     unique         A pointer to the unique data structure used by the
                    algorithm.

     paramID        The parameter identifier.

     value          The new value of the parameter.

     code           The error code as specified in cl.h.  For errors not
                    handled by the standard list, use
                    CL_ADDED_ALGORITHM_ERROR.

     format         A printf style format string.

      ...           Parameters to the printf style format string.


DESCRIPTION
     Users can add compression algorithms to the compression library by using
     clAddAlgorithm.  When the user calls the compression library for this
     added algorithm, some preprocessing is done and then the routines passed
     to clAddAlgorithm are called.

     clSetUnique and clGetUnique allow the algorithm implementation to store
     and retrieve algorithm-specific information with each instantiation of a
     compressor or decompressor.  openCompressor and openDecompressor should
     set the unique pointer to initialize algorithm-specific storage.  Other
     calls such as compress and decompress should get the unique pointer if
     they need to access the information from the handle.

     clFetchParam and clStoreParam permit algorithm implementations to access
     a handle's parameters directly, with minimal overhead.  Users of the
     codec, however, should call the standard routines clGetParam and
     clSetParam instead.

     clError is used by new algorithm implementations to report errors.
     Generally, the format string starts with the cl routine name within which
     the error occurred followed by a description of the error.


RETURN VALUES
     clAddAlgorithm returns SUCCESS, or a negative error code on failure.
     clSetUnique returns the previous unique pointer, or NULL on failure.
     clGetUnique returns the current unique pointer, or NULL on failure.
     clFetchParam returns the parameter value.


EXAMPLE
          #include <dmedia/cl.h>
           ...
          int  newScheme;
           ...
          /* Add the new algorithm */
          clAddAlgorithm("New Algorithm", CL_ALG_VIDEO,
              NEW_ALGORITHM_MAX_HEADER_SIZE,
              OpenNewCompressor, CompressNew, CloseNewCompressor,
              OpenNewDecompressor, DecompressNew, CloseNewDecompressor,
              ReadNewHeader, QueryNewScheme, QueryNewLicense,
              GetNewParams, SetNewParams,
              &newScheme);

          /* Compress a series of frames */
          clOpenCompressor(newScheme, &handle);
          for(i = 0; i < numberOfFrames; i++)
          {
              /* Get a frame from somewhere */
              ...
              clCompress(handle, 1, frameBuffer, &compressedBufferSize,


                         compressedBuffer);
              /* Write the compressed data to somewhere else */
              ...
          }
          clCloseCompressor(handle);


SEE ALSO
     CLintro(3dm), clOpenCompressor(3dm), clCompress(3dm),
     clCloseCompressor(3dm), clOpenDecompressor(3dm), clDecompress(3dm),
     clCloseDecompressor(3dm), clReadHeader(3dm), clQueryScheme(3dm),
     clQueryLicense(3dm), clGetParams(3dm), clSetParams(3dm) clAddParam(3dm),
     clSetDefault(3dm), clSetMin(3dm), clSetMax(3dm), clSetMinMax(3dm),
     clSetRange(3dm)


                                                                        Page 4