NAME

     mjpegCapture - Create a new mjpeg capture object.


SYNOPSIS

     mjpegCapture parentName ?options?


OPTIONS

  -width
     If set, should specify the desired  width  of  the  captured
     frame.  If set to 0, the object assumes the desired width is
     the same as the width of the signal  that  it  is  capturing
     from.

  -height
     If set, should specify the desired height  of  the  captured
     frame.   If  set to 0, the object assumes the desired height
     is the same as the height of the signal that it is capturing
     from.

  -xpos
     Specifies how many pixels to the right of the left  side  of
     the  incoming signal to offset the captured frame. If set to
     -1, the object attempts to center the  captured  image  hor-
     izontally. This is only effective if the -width attribute is
     set to a value less than the actual signal width.

  -ypos
     Specifies how many pixels from the top of the imcoming  sig-
     nal  to offset the captured frame. If set to -1,  the object
     attempts to center the captured image  vertically.  This  is
     only  effective  if  the -height attribute is set to a value
     less than the actual signal height.

  -squeeze
     Indicates  that  the  entire  incoming  signal   should   be
     squeezed/stretched  into  the dimensions specified by -width
     and -height. Different devices support this option  to  dif-
     ferent  degrees  (e.g.,  the Parallax board can only squeeze
     and not stretch).

  -qfactor
     Indicates the qfactor to be used for  compression.  In  this
     context  the  qfactor is used to scale the standard baseline
     quantization matrices by (qfactor/100). In  other  words,  a
     qfactor of 100 will use the standard baseline quant matrices
     unchanged, a qfactor of 200 will scale the matrices up by 2,
     etc. This is the same as the Parallax definition of qfactor.

  -device
     Specifes the capturing device to use. If set  to  "default",
     the  compiled  in  choice for a default device is used. This
     option must be set.

  -outCmd
     Indicates the command to call when sending data.  This  com-
     mand  will  be  appended  with  a  scatter  buffer  list and
     evaluated. A C interface to a scatter buffer list  accepting
     command can be specified using the @ syntax discussed in the
     application programmer's guide. The -fps option must be  set
     before the object uses the outCmd.

  -maxFrameRate
     Used to specify a maximum capturing frame rate. If set to 0,
     no maximum frame rate is enforced.

  -fps
     Used to specify the desired frame rate of capturing.

  -delay
     Specifies the latency delay to add to start  and  end  times
     for  captured frames. Essentially, newly captured frames are
     marked with (the current time + delay) as a start  time  and
     (start time + 1/fps) as an end time.

  -lts
     Indicates which lts object to use  for  timing  information.
     This  option must be set at some time before the file object
     will do anything.

  -xid
     This configuration option is only present with the  Parallax
     device.  The  parallax  device requires a window in order to
     display the incoming signal.  This option should be  set  to
     the  xid of the window to be used for this purpose. The win-
     dow must be mapped.

  -display_height
     This configuration option is only present with the  Parallax
     device.   Since  the  parallax  device displays the incoming
     signal that it captures, the  dimensions  of  the  displayed
     image  can  be different from the dimensions of the incoming
     signal. If set to 0, the display_height is assumed to be the
     same as the signal height.

  -display_width
     This configuration option is only present with the  Parallax
     device.   Since  the  parallax  device displays the incoming
     signal that it captures, the  dimensions  of  the  displayed
     image  can  be different from the dimensions of the incoming
     signal. If set to 0, the display_width is assumed to be  the
     same as the signal width.

  -display_xpos
     This configuration option is only present with the  Parallax
     device.   Since  the  parallax  device displays the incoming
     signal that it captures, the displayed picture can be offset
     from  the  upper  left  corner  of  the display window. This
     option controls the displayed picture's offset from the left
     of the display window.

  -display_ypos
     This configuration option is only present with the  Parallax
     device.   Since  the  parallax  device displays the incoming
     signal that it captures, the displayed picture can be offset
     from  the  upper  left  corner  of  the display window. This
     option controls the displayed picture's offset from the  top
     of the display window.




DESCRIPTION

     The mjpegCapture command creates a new mjpeg capture  object
     which  can be used to create a mjpeg stream from a camera or
     similar device. Data is  sent  using  the  standard  scatter
     buffer  list  method  and can be sent to any object taht can
     accept scatter buffer lists. The  data  is  intended  to  be
     eventually  received  by  a  mjpegPlay  object  which  would
     presumably display the frames in a window. The mjpeg capture
     object  can  be used in two ways. The first is to specify an
     out command and  a  frame  rate  by  setting  the  attribute
     -outCmd and -fps. When this is done, then the object period-
     ically schedules the capturing and encoding  of  frames  and
     sends  them through the out command. The object will use the
     lts for timing information. If the speed  attribute  of  the
     lts  is set to 0, the capture object will stop capturing. If
     the speed attribute is non-zero,  the  capture  object  will
     scale  the  desired frame rate and delay by the value of the
     speed. Alternatively, if the mjpeg capture object's  trigger
     command  is  invoked,  the  object  will capture a frame and
     return a tcl string representation  of  the  scatter  buffer
     list  containing  the  frame. In this way, some other object
     could drive the capture object, asking for frames as needed.
     Specific devices may also have configuration options  unique
     to  the device.  These configuration options are set through
     the configure command in exactly the same way as the general
     configuration  options  but  will  only appear if the device
     being used requires them.



WIDGET COMMANDS

     The mjpegCapture command creates a new  command  objectName.
     ObjectName is generated by concatenating the value of parent
     and a unique string which is  generated  on  the  fly.   The
     empty string is a valid value for parent.  This new command,
     objectName, is used to invoke various operations on the  new
     object.

     For more information on object names and why they  are  gen-
     erated  by  the  cm  process and not set by the user, please
     read the object management overview for the cm toolkit.

     The command objectName has the following general form:

          objectName option ?arg arg arg...?

     Option and the args determine the exact behavior of the com-
     mand.  The following commands are possible:

     objectName configure option ?value option value ...?
          Query or modify  the  configuration  options  described
          above.  If  the  object was in the ready state (see the
          ready command below), the configure  command  puts  the
          object  into the unready state, requiring the the ready
          command be given again for data to start flowing.

     objectName destroy
          Destroys the object.

     objectName deviceList
          Returns a list of valid devices.

     objecName ready
          This command readies the  object.  The  lts,  fps,  and
          outCmd  are  checked  to see whether periodic capturing
          needs to be done. If so, data is captured and sent  and
          the  object queues itself to do so again in the future.
          Before ready can be invoked, the -lts  option  must  be
          specified.  In  addition,  specific devices may require
          device specific attributes to be set.

     objectName unready
          This command unreadies the object  stopping  data  from
          being sent. A call to the object's trigger command will
          return an empty scatter buffer list if  the  object  is
          unready.

     objectName refresh
          This command may or may not do  anything  depending  on
          the  device.  If  the  device  requires  a  window that
          displays what is being captured, this  command  can  be
          used  to   signal  the  device  that the display window
          needs to be refreshed due to an expose  event  or  some
          other reason.

     objecName trigger
          When this command is invoked,  the  object  (if  ready)
          will capture a frame and return a tcl representation of
          a scatter bufffer list containing the frame.  This com-
          mand  can be used by other objects to drive the capture
          object instead of the outCmd method.

     objectName stats
          Returns a list of numbers that represent the number  of
          frames  captured and the number of bytes captured since
          the last time this command was called and/or the object
          readied.



KEYWORDS

     cm, mjpeg, capture, mjpegCapture, cm toolkit


AUTHORS

     Ketan Mayer-Patel