NAME

     mpegPlay - Create a new mpeg play object.


SYNOPSIS

     mpegPlay parentName ?options?


OPTIONS

  -width
     If set, should specify the width of the window where data is
     supposed  to  be  displayed. If not set (i.e. set to 0), the
     object assumes that the window is as big as the mpeg frames.
     This  value  is  used when the image is being resized to fit
     the display window (see the -sqeeze option).

  -height
     If set, should specify the height of the window  where  data
     is being displayed.  If not set, the object assumes that the
     window is as big as the mpeg frames.  This value is used for
     centering  the  image  in  the display window. This value is
     used when the image is being resized to fit the display win-
     dow (see the -squeeze option).

  -xpos
     Specifies how many pixels to the left of the  left  side  of
     the display window to offset the image. If set to -1 and the
     squeeze option is not set, the object attempts to center the
     image horizontally.

  -ypos
     Specifies how many pixels below the top edge of the  display
     window  to  offset  the  image. If set to -1 and the squeeze
     option is not set, the object attempts to center  the  image
     vertically.

  -squeeze
     If non-zero, indicates to the resource to resize  the  image
     to  the size of the display window if possible. Not all dev-
     ices will be able to support this.

  -xid
     Should be set to the X window id of the display  window.  If
     the  display  window  is a Tk widget, this value can be gen-
     erated with the "winfo id" command. This slot  must  be  set
     for  the  resource  object  to work. Attempting to issue the
     "ready" command to the object when this  slot  has  not  yet
     been set will generate an error.

  -device
     Should be set to the decoding device type. If "default", the
     compiled  default  device will be used. Current device types
     are: "software". This slot must  be  set  for  the  resource
     object  to  work. Attempting to issue the "ready" command to
     the object when this slot has not yet been set will generate
     an error.

  -lts
     Should be set to the logical time system object (lts) to  be
     used  for  synchronization.   This  slot must be set for the
     resource object to work. Attempting  to  issue  the  "ready"
     command  to  the  object when this slot has not yet been set
     will generate an error.

  -maxFrameRate
     Indicates the maximum frame rate to display. If set to 0, no
     maximum is imposed.  Not currently implemented.



DESCRIPTION

     The mpegPlay command create a new mpeg play object which can
     be  used  to  display  mpeg  frames in a window. This object
     requires that its lts, xid, and device slots be filled.  The
     object  display frames in the window specified by xid. Frame
     start and end times sent with the mpeg data are compared  to
     the  current  lts  time.  If  the frame end time has already
     passed, the frame is dropped (i.e. not  displayed).  If  the
     frame  start  time has yet to arrive, the frame is scheduled
     for future display. If the current time is in the  range  of
     start  to  end  time,  the  frame  is displayed immediately.
     Whether a frame is decoded in time for its display  time  is
     variable with the device used.
     MpegPlay objects can be in  one  of  two  states:  ready  or
     unready.  When  first  created  the object is in the unready
     state. The object does nothing in the unready state and  all
     buffers  passed to it will be dropped. The object can be put
     into the ready state by calling the object's ready  command.
     All  of  the required slots (i.e. lts, xid, and device) must
     be set before calling the ready command.  Any  call  to  the
     object's  configure  command that set a slot value automati-
     cally puts the object in the unready  state  and  the  ready
     command  must be given again to put the object in action. If
     the configure command was used to query a slot's value,  the
     ready/unready state is unchanged.

     Each mpegPlay object registers  the  following  event  types
     with the cmBind mechanism:
          <FRAME_DROPPED>
               Occurs whenever a frame that has been received  is
               thrown away without being decoded.
          <FRAME_RECEIVED>
               Occurs whenever a frame is received.
          <FRAME_PLAYED>
               Occurs whenever a frame is displayed.
          <FRAME_DECODE_BEGIN>
               Occurs  whenever  a  frame  is  first  chosen  for
               decoding.
          <FRAME_DECODE_DONE>
               Occurs whenever a frame completed decoding.

     In  addition  the  following  substitution  parameters   are
     defined for scripts associated with any of these events:
          %s -- logical start time
          %e -- logical end time
          %l -- length of frame data
          %w -- decoded frame width
          %h -- decode frame height
          %t -- type of frame (1 == I, 2 == P, 3 == B)
          %p -- index number of past reference frame
          %n -- index number of future reference frame
          %i -- index number of this frame


WIDGET COMMANDS

     The mpegPlay  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 ready
          This command readies the  object.  The  required  slots
          (i.e. lts, xid, and device) must be validly set.

     objectName unready
          This command unreadies the object  stopping  data  from
          being decoded or displayed.

     objectName accept <scatter_buffer_list>
          This command accepts <scatter_buffer_list> as mpeg data
          to be displayed. A standard scatter buffer list accept-
          ing C  interface  to  this  command  is  registered  as
          <objectName>.accept.

     objectName stats
          Returns a list of statistics about the device's perfor-
          mance.  Exact  format  of this list has not been worked
          out yet. Currently does nothing.

     objectName refresh
          Causes the last frame to be displayed to  be  displayed
          again.  This  command  is  useful  to  deal with expose
          events that occur in the display window.

     objectName deviceList
          Returns a list of devices  --  valid  strings  for  the
          -device configuration option.




KEYWORDS

     cm, mpeg, mjpegPlay, play, cm toolkit


AUTHORS

     Ketan Patel (kpatel@cs.berkeley.edu)