clOpenDemux(3dm)

NAME
     clOpenDemux, clDemux, clCloseDemux - Demultiplex into video and audio
     streams

SYNOPSIS
     #include <dmedia/cl.h>

     int clOpenDemux(int scheme, CLhandle *handlePtr)
     int clDemux(CLhandle handle, int count)
     int clCloseDemux(CLhandle handle)

ARGUMENTS
     scheme         The demultiplexing scheme to use.

     handlePtr      A pointer to the returned handle of the demultiplexer.
                    Used by subsequent calls to identify the demultiplexer.

     handle         A handle to the demultiplexer.

     count          The number of iterations to execute.  The amount of
                    processing done during each iteration is scheme and data
                    dependent.  count may also be specified as
                    CL_CONTINUOUS_BLOCK or CL_CONTINUOUS_NONBLOCK.


DESCRIPTION
     clOpenDemux opens a demultiplexer for a given scheme.  It is called
     before clDemux or any call that requires a demultiplexer handle.
     clCloseDemux closes the demultiplexer after which handle is no longer
     valid.

     clDemux takes no buffer arguments so it always invokes the Implicit
     Buffering model (see CLintro(3dm)).  An input buffer of type CL_BUF_MUX,
     and output buffers of types CL_BUF_VIDEO and CL_BUF_AUDIO, must have been
     created previously with clCreateBuf.  The input buffer is filled with
     calls to clQueryFree, clUpdateHead, and clDoneUpdatingHead.  The output
     buffers are emptied with calls to clQueryValid and clUpdateTail.

     Buffers should be appropriately sized for proper execution of clDemux.
     The input buffer should have a minimum capacity of CL_MUX_BUFFER_SIZE.
     The output buffers should have minimum capacities of CL_VIDEO_BUFFER_SIZE
     and CL_AUDIO_BUFFER_SIZE. These parameters may be determined by calling
     clGetParams, after first calling clReadHeader to configure the
     demultiplexer.

     If count is non-negative, clDemux attempts to perform count iterations of
     the demultiplexing operation.  The actual amount of data processed in
     each iteration is scheme and data dependent.  The call to clDemux may
     consume up to CL_MUX_BUFFER_SIZE * count bytes of multiplexed data.  This
     may produce up to CL_VIDEO_BUFFER_SIZE * count bytes of video data, and
     up to CL_AUDIO_BUFFER_SIZE * count bytes of audio data.  The call does
     not return until processing is completed.
     If count is specified as CL_CONTINUOUS_BLOCK or CL_CONTINUOUS_NONBLOCK
     then clDemux continues until the input buffer is marked done, or a call
     to clCloseDemux is made.  CL_CONTINUOUS_NONBLOCK differs from
     CL_CONTINUOUS_BLOCK in that the call to clDemux returns immediately while
     the demultiplexing occurs in a separate thread.

     Several demultiplexers can be open simultaneously.  handle identifies
     which one is being referenced.


RETURN VALUES
     Each routine returns a negative error code if the call fails.  Upon
     success, clOpenDemux and clCloseDemux return SUCCESS, and clDemux returns
     either the count actually processed or, in the case of
     CL_CONTINUOUS_NONBLOCK, returns SUCCESS immediately.


EXAMPLE
          #include <dmedia/cl.h>

          int paramValueBuffer[][2] = {
              CL_MUX_BUFFER_SIZE, 0,
              CL_VIDEO_BUFFER_SIZE, 0,
              CL_AUDIO_BUFFER_SIZE, 0,
          };

          /* Open the demultiplexer */
          clOpenDemux(CL_MPEG1_SYSTEMS_SOFTWARE, &handle);

          /* Configure the demultiplexer by reading the header */
          headerSize = clQueryMaxHeaderSize(CL_MPEG1_SYSTEMS_SOFTWARE);
          /* Get the header data from somewhere */
           ...
          clReadHeader(handle, headerSize, header);

          /* Allocate buffers of the required size */
          clGetParams(handle, (int *)paramValueBuffer, 6);
          clCreateBuf(handle, CL_BUF_MUX, paramValueBuffer[0][1], 1, NULL);
          clCreateBuf(handle, CL_BUF_VIDEO, paramValueBuffer[1][1], 1, NULL);
          clCreateBuf(handle, CL_BUF_AUDIO, paramValueBuffer[2][1], 1, NULL);

          /* Demultiplex a few iterations */
          for(i = 0; i < N; i++)
          {
              /* Keep the input buffer full */
               ...
              clDemux(handle, 1);
              /* Write the video and audio data to somewhere */
               ...
          }

          /* Close the demultiplexer */
          clCloseDemux(handle);



SEE ALSO
     CLintro(3dm), clReadHeader(3dm), clGetParams(3dm), clCreateBuf(3dm),
     clQueryFree(3dm), clUpdateHead(3dm), clQueryValid(3dm),
     clUpdateTail(3dm), clDoneUpdatingHead(3dm)