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)