NAME

     bufferCapture - Tcl interface to CMT Buffer Capture object



SYNOPSIS

     bufferCapture parent
     <obj> configure [-outCmd  [newCmd]]  [-verbose  [level]]  [-
     filename [fileName]]
     <obj> destroy
     <obj> accept scatterBufferList
     <obj> open
     <obj> close



DESCRIPTION

     The Tcl bufferCapture command creates a CMT  buffer  capture
     object  and  returns the name of the new object.  BufferCap-
     ture objects are  useful  for  debugging  CMT  applications.
     When  inserted into a CMT graph, they print certain informa-
     tion about every buffer that  goes  by  before  passing  the
     buffers  on  to the outCmd and possibly capture the contents
     of the buffers into a specified file.  The degree of  detail
     can be controlled using the verbose flag.

     The name of the new object is  internally  generated,  using
     the  string  parent as the leading characters.  The returned
     name is the name of a new Tcl command that can  be  used  to
     send  messages  to the object.  BufferCapture objects under-
     stand the following messages:


  object destroy
     Destroys the buffer capture object.

  object accept
     Used to pass a scatter buffer list  to  the  buffer  capture
     object.   A  C  interface  to this function is registered as
     <objectName>.accept.

  object configure ?-options?
     Sets configuration parameters  for  object.   Valid  options
     are:

          -outCmd cmd
               Where to send data as it arrives.  Cmd should be a
               string  conforming  to the usual CMT semantics for
               passing data between objects.  That is, cmd should
               be either the name of a Tcl procedure to be called
               every time data is available, or a string  of  the
               form  @object.accept  where  object  is  some  CMT
               object that will accept the data.

          -verbose level
               Specifies the degree of detail with which  buffers
               in  the scatter-buffer lists passed to the objects
               accept command are printed.  If level is less than
               1,  no  information  is printed.  If level is 1 or
               greater, the buffer name of every  buffer  in  the
               scatter-buffer  list and current time are printed.
               If level is 2 or greater, the  type  and  size  of
               each  chunk  of every buffer in the scatter-buffer
               list is  printed.   If  level  is  3  or  greater,
               detailed  information  about the headers contained
               in each chunk of  every  buffer  in  the  scatter-
               buffer  list   is  printed.  The default value for
               level is 2.

          -lts ltsName
               Specifies the name of the LTS to use when printing
               time values.  If ltsName is the empty string, time
               values are printed using the value on  the  system
               time  clock.   Otherwise,  the current time of the
               lts is used.  In combination with verbose level of
               3  or more, this option can be useful in determin-
               ing if buffer are arriving early or late.

          -filename fileName
               Specifies the name of the  file  to  write  buffer
               data into. Writing into the file does not commence
               until the open command is given (see below) and is
               suspended when the close command is given.


  object open
     This command instructs the object to open the file specified
     by  the configuration option -filename in order to write the
     actual contents of the  data  buffers.  Content  is  written
     based  on  the stream type of the data. Currently only audio
     data is fully supported although  the  object  will  capture
     data  from  any  buffers  generically  typed as CM_DATA_SEG.
     Since most streams (including mpeg and mjpeg) use this  gen-
     eric type for non-header data, this object can still be use-
     ful.

  object close
     This command suspends output to the file.


DATA PASSING

     The buffer capture object obeys the CMT semantics for  pass-
     ing  data  between  objects.   To summarize, you can set the
     output  function  of  another  object  to  be   the   string
     @object.accept  where object is the name of a buffer capture
     object.   Then  data  produced  by  the  other  object  will
     automatically  be handed to the buffer capture and on to the
     object specified by the outCmd.




SEE ALSO

     cmwish(1), cmx(1)



AUTHOR

     Brian Smith (bsmith@cs.cornell.edu)