NAME

     mjpegFile - Create a new mjpeg file object.


SYNOPSIS

     mjpegFile parentName ?options?


OPTIONS

  -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.

  -sendAhead
     Indicates how many seconds  in  advance  to  send  data.  By
     default, this value is set at 0.2 seconds.

  -bandwidth
     Indicates maximum number of bytes per second to send. If set
     to  0,  no  maximum  is  enforced.  For  this option to work
     correctly, cycleTime must not  be  non-zero.  See  cycleTime
     option below.

  -cycleTime
     Indicates how many seconds worth of data to send at a  time.
     If  set  to 0, the object will send data one frame at a time
     and schedule itself to be called again when the  next  frame
     needs to be sent.

  -fileName
     Indicates which file to use as a mjpeg file. If this file is
     not  in  the  correct mjpeg chunk file format, an attempt to
     read the file as  a Parallax XVideo JMovie, a .vid file, and 
     as  a J300 .avi file is made. If all of these attempts fail, 
     an error is returned and no file is opened.

  -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.

  -maxFrameRate
     Used to specify a maximum sending frame rate. If set  to  0,
     no maximum frame rate is enforced. This option only works if
     cycleTime is non-zero (see cycleTime above).


DESCRIPTION

     The mjpegFile command creates a new mjpeg file object  which
     can be used to read mjpeg data from a file and send the data
     to another object. Data is sent using the  standard  scatter
     buffer  list  method  and can be sent to any object that can
     accept scatter buffer lists. The  data  is  intended  to  be
     eventually  received  by  a mjpegResource object which would
     presumably display the frames in a window.  The  mjpeg  file
     object  expects  the data to be stored on disk in the format
     of a mjpeg chunk file. If this format is  not  true  of  the
     file  specified,  the  object attempts to read the file as a
     j_movie,  .vid,  or .avi  file  and  parse  the  information  
     normally found in a chunk file on the fly.


WIDGET COMMANDS

     The mjpegFile 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  appendSegment  <clip_start>  <clip_end>  ?-start
     <logical_start>? ?-end <logical_end>?
          Specifies what part of the file should  be  played  and
          when. The values <clip_start> and <clip_end> specify in
          what part of the file is to be played. For example, the
          values  0.0  and  10.0 would indicate that the first 10
          seconds of the file are to be played. The option -start
          and  -end  parameters indicate when in terms of logical
          time (i.e. in terms of the lts set with the -lts confi-
          guration option) the segment should be played.  If nei-
          ther -start  or  -end  is  indicated,  the  segment  is
          assumed  to be played at logical time 0.0. If -start is
          indicated alone, the segment is set to  start  at  that
          time. If -end is indicated alone, the segment is set to
          play in such a way as to end  at  that  time.  If  both
          values  are  indicated, the segment is set to start and
          end  at  the  times  specified  with  the   appropriate
          stretching  or  squeezing  necesary to make the segment
          fit. This command returns a segment id in the  form  of
          an  integer that can be used to refer to the segment in
          other command. If a segment is specified to play  at  a
          logical  time  during  which  a  different  segment has
          already been set to play, an error is returned.

     objectName deleteSegment <segment_id>
          Removes the segment identified by <segment_id> from the
          list of segments to be played.

     objectName clearSegments
          Clears the list of segments to be played. Equivalent to
          deleting  each segment individually with the deleteSeg-
          ment command.

     objectName segmentInfo <segment_id>
          Returns  a  list  of  information  about  the   segment
          <segment_id>. This list is in the form:
               {clip_start clip_end log_start log_end  num_frames
               max_size}
          where clip_start and clip_end specify which part of the
          file  is  being  played,  log_start and log_end specify
          when the segment is being played according  to  logical
          time,  num_frames  is  the number of frames in the seg-
          ment, and max_size is the largest frame  size  in  this
          segment in bytes.

     objectName info
          Returns a list of information about the  file  in  gen-
          eral. This list is in the form:
               {num_frames clip_length max_size width height}
          where num_frames is the total number of frames  in  the
          file, clip_length is the length of the file in seconds,
          max_size is the largest frame size in the  file,  width
          is the width of each frame, and height is the height of
          each frame.  If width or height is set to 0, this indi-
          cates that the value is undetermined (i.e.  variable or
          not known).

     objectName ready
          This command readies the object. The lts is checked  to
          see  if  data needs to be sent. If so, data is sent and
          the object queues itself  to  send  data  according  to
          cycleTime  and the segments specified. Before ready can
          be invoked, the -lts option must be  specified  and  at
          least one segment specified. If either of these are not
          true, the ready command will effectively do nothing.

     objectName unready
          This command unreadies the object  stopping  data  from
          being sent.



KEYWORDS

     cm, mjpeg, file, mjpgc, mjpegFile, cm toolkit


AUTHORS

     Ketan Patel (kpatel@cs.berkeley.edu)