clOpenMux(3dm)

NAME
     clOpenMux, clMux, clCloseMux - Multiplex video and audio streams

SYNOPSIS
     #include <dmedia/cl.h>

     int clOpenMux(int scheme, CLhandle *handlePtr)
     int clMux(CLhandle handle, int count)
     int clCloseMux(CLhandle handle)

ARGUMENTS
     scheme         The multiplexing scheme to use.

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

     handle         A handle to the multiplexer.

     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
     clOpenMux opens a multiplexer for a given scheme.  It is called before
     clMux or any call that requires a multiplexer handle.  clCloseMux closes
     the multiplexer after which handle is no longer valid.

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

     Buffers should be appropriately sized for proper execution of clMux.  The
     input buffers should have minimum capacities of CL_VIDEO_BUFFER_SIZE and
     CL_AUDIO_BUFFER_SIZE.  The output buffer should have a minimum capacity
     of CL_MUX_BUFFER_SIZE.  These parameters may be determined by calling
     clGetParams, after first calling clSetParams to provide the multiplexer
     with any initialization information it may need (e.g. pack size,
     bitrate).

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

     Several multiplexers 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, clOpenMux and clCloseMux return SUCCESS, and clMux 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_VIDEO_BUFFER_SIZE, 0,
              CL_AUDIO_BUFFER_SIZE, 0,
              CL_MUX_BUFFER_SIZE, 0,
          };

          /* Open the multiplexer */
          clOpenMux(CL_MPEG1_SYSTEMS_SOFTWARE, &handle);

          /* Configure the multiplexer by setting some params */
          clSetParam(handle, CL_BITRATE, 1500000);

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

          /* Multiplex a few iterations */
          for(i = 0; i < N; i++)
          {
              /* Keep the input buffers full */
              ...
              clMux(handle, 1);
              /* Write the multiplexed data to somewhere */
              ...
          }

          /* Close the multiplexer */
          clCloseMux(handle);

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