NAME

     yuvFilter - Create a new yuv filter object.


SYNOPSIS

     yuvPlay parentName ?options?


OPTIONS

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

  -FrameRate
     Indicates the frame rate the filter outputs.

  -sendAhead
     Indicates how many seconds in advance to send data.

  -filter
     This determines what type of filter the  object  implements.
     Can be "textOverlay", "pictureInPicture", or "fade".

  -yoffset
  -xoffset
     Used by "textOverlay" and "PictureInPicture".   The  offsets
     (from  top-left  corner  of  image)  of superimposed text or
     video.

  -fontFile
     Pathname to a bdf font file to be used for displaying text.

  -text
     A character string superimposed over the video in a  "textO-
     verlay" filter.

  -color
     The color of the "textOverlay" font.

  -percent
     Used by "fade".  Controls how the two  input  video  streams
     are mixed.  100 would display only the first video stream, 0
     only the second.

  -scale
     Used by "PictureInPicture".  Determines how large the super-
     imposed video appears.  A scale of 2 implies a video half as
     small in both dimensions.


DESCRIPTION

     The yuvFilter command creates a new yuv filter object  which
     can be used to perform various special effects on one or two
     input video streams.  This object requires that its lts slot
     be filled in order to function.

     Three filters are currently implemented:  textOverlay,  pic-
     tureInPicture, and fade.

     TextOverlay only operates on one input stream  (see  acceptA
     below).   It  takes  a user defined string, font, and color,
     and superimposes the string onto the incoming video.

     PictureInPicture takes two input streams  (see  acceptA  and
     acceptB below) and superimposes a scaled version of stream B
     onto stream A.

     Fade combines two video streams into  one  stream,  using  a
     percentage to determine the relative weights of the inputs.

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

     Any call to the  object's  configure  command  automatically
     puts  the  object in the unready state and the ready command
     must be given again to put the object in action.



WIDGET COMMANDS

     The  yuvPlay  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
          pThis 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     acceptA     <scatter_buffer_list>     acceptB
     <scatter_buffer_list>
          These commands accept <scatter_buffer_list> as yuv data
          to  be inputed into filter routines. A standard scatter
          buffer list accepting 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.



KEYWORDS

     cm, yuv, cm toolkit


AUTHORS

     David Simpson (davesimp@cs.berkeley.edu)