Page 1
mvp(3dm)mvp(3dm)NAMEmvp - Multiport Video Processor for the O2 system
DESCRIPTION
The MVP driver supports the O2 video input and output as well as the
screen capture devices. It was designed and written to the device
dependent specification of the Video Library (VL) replacement for O2, DVL
(Direct Video Library, ie., no video daemon). This new implementation of
the VL API has many new benefits:
* Events are naturally synchronous with data and there is
guaranteed an event for each data buffer.
* Turn around time and latency for VL commands is greatly reduced
since commands are executed directly instead of being passed to
the video daemon.
* It is fully integrated with Digital Media Buffers and DVL
supports a new buffering API that is compatible with other media
libraries, including the new compression library (dmIC), and the
new Movie Library.
* There is also a new buffer API for OpenGL on O2 that allows
exchanging data between video, graphics and compression without
the need to copy data from one format to another.
* The synchronization of Audio and Video is much better controlled
and is more easily attainable in the user process.
Video Input/Output Channels
The Video Input/Output capabilities of the O2 are fully supported by
the MVP driver. This includes both video and screen capture. Some of
the features of the O2 video system include:
* Video Input Connectors: On the AV1 audio/video interface there
are the SVideo and Composite inputs as well as the digital camera.
A "dongle" is also available that can be attached to the camera
connector for 601 digital video input [contact SGI sales for more
information.]) On the AV2 audio/video interface card there are 2
BNC input digital connectors. In addition, the Graphics Screen
can be an input and any output video may also be used as an input.
Page 2
mvp(3dm)mvp(3dm)
* Video Input Channels: 2 independent input channels supporting
4:2:2 YUV or 1 channel supporting 4:2:2 YUV and 1 channel
supporting Alpha.
* Video Output Connectors: On the AV1 interface, there are the
Svideo and Composite input and the same "dongle" refered to above
has a 601 digital video output. On the AV2 audio/video interface
card there are 2 BNC output digital connectors.
* Video Output Channels: 1 output channel supporting either 4:2:2
YUV (to both output ports) or 4:2:2:4 YUVA (to two combined output
ports) (see VL_MVP_OUTPUT_ENABLE.)
* Clipping and down-scaling of image to virtually any size with
independent zooming in the X and Y directions on input. Padding
of images on output (see VL_SIZE, VL_OFFSET, VL_ASPECT, VL_ORIGIN,
and VL_MVP_ZOOMSIZE).
* Either non-square or square (PAL or NTSC) pixel format in memory
(see VL_TIMING).
* Pbuffer and Mipmap generation for quick and efficient processing
with the O2 Graphics Engine (see VL_LAYOUT).
* Field or interleaved frame modes (see VL_CAP_TYPE).
* Various RGB and YUV colorspaces (see VL_PACKING).
APPLICATION INTERFACE
Basic Program Structure
The basic MVP VL application has the following components. All of
these calls are described in the following sections with further
information available in both the VL manpages and the Digital Media
Programmer's Guide.
Preliminary path set up:
vlOpenVideo open the video server.
Page 3
mvp(3dm)mvp(3dm)
vlGetDeviceList discover which devices and nodes are connected to
this system.
vlGetNode get the source and drain nodes.
vlCreatePath create a video path with the source and drain nodes
specified.
vlSetupPaths set the path up to be usable given the access
requested.
vlDestroyPath remove a video path.
Specific control settings:
vlSetControl set various parameters associated with the video
transfer.
vlGetControl get various parameters associated with the video
transfer.
Preparing to capture or output video to/from memory:
vlCreateBuffer
vlRegisterBuffer if needed, create and register a buffer using
Digital Media Ring Buffers (DMRB).
dmBufferCreatePool
vlDMPoolRegister if needed, create and register a buffer pool using
Digital Media Buffers (dmBuffers).
Starting and controlling the video transfer:
vlBeginTransfer initiate the transfer
vlEndTransfer terminate the transfer
Page 4
mvp(3dm)mvp(3dm)
vlNextEvent handle events from the video device using DMRB
interface.
vlEventRecv handle events from the video device using dmBuffers
interface.
Moving data buffers to and from the video system:
vlGetNextValid
vlPutValid get and put buffers using DMRB interface.
vlEventToDMBuffer
vlDMBufferSend get and send buffers using dmBuffers interface.
VL Interface Routines
Details of the VL interface routines that are specific to MVP are
described below.
vlOpenVideo(char *name)
This will load the VL library .dso into memory if it is not
already resident and it then will load any .dso's for the video
devices attached to the system. For MVP, when it is loaded and
initialized does an inventory check of which options are available
and builds the node and control tables from this information.
Additionally, MVP will sense the timing of the connected video
inputs and decide on a default input (see VL_DEFAULT_SOURCE).
vlGetDeviceList(VLServer, VLDevList *)
Returns the "mvp" device among any others that may be connected to
the system as well as which nodes are available on those devices.
Note that this list can be displayed using the vlinfo command.
vlInitDevice()
Resets the device to a known state.
Page 5
mvp(3dm)mvp(3dm)vlSaveSystemDefaults()
Saves whatever control settings are currently active into a
"system defaults" file, which for DVL is $HOME/.videopanelrc.
This file may be edited to adjust the settings for particular
applications.
vlRestoreSystemDefaults()
Restores settings saved by "vlSaveSystemDefaults()".
vlRestoreFactoryDefaults
Restores the control settings that were initially set by the
system vendor.
VL Path Routines
vlGetNode(VLServer, type, kind, number)
A node satisifying the "type", "kind" and "number" is returned.
The types supported by MVP are VL_SRC, VL_DRN and VL_DEVICE. The
kind may be one of VL_VIDEO, VL_MEMORY, or VL_SCREEN. The number
should be a valid number from the node table obtained with the
vlGetDeviceList() routine.
Or the number may be VL_ANY which for the VL_SRC/VL_VIDEO node
specifies that the user program wants the "VL_DEFAULT_SOURCE" node
that is automatically set when the video program starts or is
selected via the Video Control Panel.
VL_ANY for the VL_MEM node specifies that a non-busy memory node
should be selected. (See vlSetupPaths() below for more details.)
In addition to the above effects, the handling of the node may be
different after the stream is pre-empted and restarted (see
VLStreamPreempted() below).
The following is a description of each of the nodes that the
hardware and driver support. The complete node list can be
obtained with the vlinfo command. See the example near the end of
this manpage for selecting video input nodes.
VL_VIDEO
The Video nodes are the external connections to the system,
with some exceptions listed below. To select the desired
node, find the entry in the node list for the device "mvp" in
the return argument of vlGetDeviceList() and then use the
node "number" in the vlGetNode call.
The Loopback video node supports capturing back into the
system the video that is being output via Video Out. There
are uses beyond diagnostics such as generating graphic
Page 6
mvp(3dm)mvp(3dm)
texture maps from decompressed video.
Note that since all outputs are active simulataneously, they
are treated as a single Node. Which part of the output video
stream that is routed to which connecter is selected by the
VL_MVP_OUTPUT_ENABLE control.
To use the Digital Video in and out with an AV1 card, a "D1
Dongle" is required [contact SGI sales for more information].
Alternatively, the O2 Digital Camera may be connected as an
input only device, which has a builtin microphone.
VL_SCREEN
The Screen node is the Graphics Engine capture path. It
supports capturing a section of the screen as well as the
full screen. The data is captured after the Gamma Correction
is applied, but before the Digital to Analog conversion.
VL_MEM
The Memory nodes are the DMA engines and there are 4
available, 2 for input from video, 1 for input from the
screen and 1 for output to video.
vlCreatePath(VLServer, VLDev, VLNode, VLNode)
The vlCreatePath will create a path that has the first VLNode as
the source and the second VLNode as the drain. If either are
VL_ANY then both must be VL_ANY and the path is not usable as a
data transferring path until nodes are added with vlAddNode().
A path that is not intended to be used as a data transfer path may
have as many nodes attached as they exist for a given device. The
use of this kind of path is primarily for getting and setting the
various controls of the different video devices and is known as a
"DevPath".
If the path is not a DevPath, then the source and drain must be
valid nodes and for MVP, the only other connection allowed is a
VL_DEVICE node.
Note that in DVL/MVP, a path is unique to a process only, and not,
as in the old VL, unique within a system. That means that a
VLPath can only be used within the user process that created it,
and can not be passed to other processes.
Page 7
mvp(3dm)mvp(3dm)
vlDestroyPath(VLServer, VLPath)
The path specified is removed from the system.
vlAddNode(VLServer, VLPath, VLNode)
vlAddNode is used to add nodes to a path. The nodes are gotten
with vlGetNode().
vlRemoveNode(VLServer, VLPath, VLNode)
The node is removed from the path.
vlSetupPaths(VLServer,VLPathList,count,ctrlUsage,strmUsage)
VLSetupPaths() takes an array of paths. It attempts to set up
these paths one by one in the order they appear in the array. If
a path set up fails, the call is aborted at the point of failure.
No attempt is made to unwind the actions already performed: paths
that got set up are left set up, the path that failed is left at
its former usage levels (though there may have been side effects),
and paths following that one in the path array that failed are not
set up.
The following usages may be specified:
VL_DONE_USING
VL_READ_ONLY
VL_SHARE
VL_LOCK
Note that if either usage is specified as VL_DONE_USING then both
must be specified as VL_DONE_USING. This essentially releases the
resources held by the path.
To set up each path in the array of paths, the following algorithm
is used: For each node on the path, the desired new usage level
is compared to the current usage level (for both control and
stream usage), using the following table to determine one of three
outcomes:
OK - the node can be put into this new usage level
PREEMPT - the node can be put into this new usage level,
but the other path must get preempted off
FAIL - the node cannot be put into this new usage level
If FAIL occurs, the path cannot be set up as desired, and the call
to VLSetupPaths() fails at this point. If PREEMPT occurs, the
other path is put on a list of paths to be preempted if this
vlPathSetup() doesn't fail. All the nodes are checked before any
preempting is done, and all preempting is done before this path is
actually set up.
Page 8
mvp(3dm)mvp(3dm)
The test must be made for each node in the path to be set up,
against all paths that already have the node. If any FAIL's occur
in any of these tests, the path set up fails. Otherwise, it will
preempt all paths that generated a PREEMPT result for any of the
tests.
New Usage
+------------+------------+---------+---------+
Current | DONE_USING | READ_ONLY | SHARE | LOCK |
Usage +============+============+=========+=========+
DONE_USING | OK | OK | OK | OK |
+------------+------------+---------+---------+
READ_ONLY | OK | OK | OK | OK |
+------------+------------+---------+---------+
SHARE | OK | OK | PREEMPT | PREEMPT |
+------------+------------+---------+---------+
LOCK | OK | OK | FAIL | FAIL |
+------------+------------+---------+---------+
This table is used for both Control Usage and Stream Usage with
one difference: if a node is at control SHARE usage, another node
may also take it in control SHARE usage, but if a node is in
stream SHARE usage, its path gets preempted when another node
takes stream SHARE usage.
In addition, if the node is a specific VL_SRC/VL_VIDEO node, then
two paths may have it's streamUsage VL_LOCK, though only one of
it's controlUsage can have VL_LOCK access. This allows a user
application to lock both inputs to a video node to prevent either
one of them from becoming preempted.
If a path cannot be set up with the desired access it is then
automatically set up with VL_READ_ONLY access. This allows the
user program to wait for Stream and/or Control Available events
and reattempt the vlSetupPaths.
MVP Controls
There are 2 types of VL Controls in MVP, "path" controls and
"device" controls. The distinction between these two is:
Path Controls are those controls that are capable or actively
controlling a transfer, suce as VL_SIZE, VL_OFFSET, VL_ZOOM, etc.
These controls are private to a path and any changes (with some
exceptions) cause events to be sent ONLY to the process owning the
path. Note these controls are active while the path is
transferring, and retain their values when the transfer is suspended
for any reason. In practice, this means the user program should be
able to set up the desired transfer controls, and start the transfer
after any preemption without needing to restore controls to their
Page 9
mvp(3dm)mvp(3dm)
previous values.
Device Controls are those controls that are outside the realm of a
"path" and could possibly effect the data that another path is
processing. These include such controls as VL_BRIGHTNESS and
VL_CONTRAST. And since most of these controls directly affect some
hardware change, they will retain their values after the paths are
removed.
In the descriptions below, the first name is the VLControl name, the
second is the ascii string associated with the control, the third
specifies which nodes this control can be applied to, the fourth
specifies whether it is a path control or a device control, and the
fifth specifies the type of value the control accepts,
Note that the ascii name is used to assign values to controls in the
VL System Defaults file and can also be found in the control table
gotten via a vlGetControlList().
Nodes the control may be applied are:
(VL_SRC/VL_VIDEO) - source video node
(VL_DRN/VL_VIDEO) - drain video node
(VL_ANY/VL_VIDEO) - source or drain video node
(VL_SRC/VL_SCREEN) - source screen node
(VL_SRC/VL_MEM) - source memory node
(VL_DRN/VL_MEM) - drain memory node
(VL_ANY/VL_MEM) - source or drain memory node
-RO - read only for that node
Value types are:
"(t,f)" - boolVal - true or false
"(n,d)" - fractVal - fraction value
"(int)" - intVal - integer value
"(x,y)" - xyVal - integer X and Y values
VL_DEFAULT_SOURCE
"default_input" (VL_SRC/VL_VIDEO) device (int)
Specifies which of the input nodes is to be considered the
"default" input. This is automatically set up when the video
driver is loaded according to the following table:
Page 10
mvp(3dm)mvp(3dm)
Input signal(s) active Default_Source
digital svideo composite camera
yes x x x digital
no yes x x svideo
no no yes x composite
no no no yes camera
no no no no composite
For example, if a VCR is connected to the SVideo input and it is
powered on, then it will be the default input.
When the VL_DEFAULT_SOURCE is changed a VLDefaultSource event is
sent to all processes that have this event enabled in their
vlEventMask (see MVP Events below).
VL_TIMING
"timing" (VL_SRC/VL_VIDEO) device (int)
The VL_TIMING control is adjusts the video filter for different
video standards. There are currently 4 available in MVP:
VL_TIMING_525_CCIR601
VL_TIMING_625_CCIR601
The 525 (NTSC) or 625 (PAL) timing stardards are specified
and the pixels are considered to be in the accepted video
aspect ratio (4:3) for that standard (this is also known as
"non-square" timing).
VL_TIMING_525_SQ_PIX
VL_TIMING_625_SQ_PIX
The 525 (NTSC) or 625 (PAL) timing stardards are specified
and in addition a square <-> non-square pixel filter is
engaged so that in memory, the pixels are in a 1:1 aspect
ratio which is compatible with the Graphics Engine.
When these timings are applied to a path that has the O2 Digital
Camera attached, then the 525 (NTSC) timing standard is
interpreted to mean that external pixels are in a 1:1 aspect
ratio, and there are no "non-square" or PAL formats available for
the internal pixels.
Note that the application program should always check the default
VL_SIZE after a timing change to determine what the size of the
resultant images will be.
For the square to non-square conversion a ratio of 11/10 for NTSC,
and a ratio of 11/12 for PAL is applied.
Page 11
mvp(3dm)mvp(3dm)MVP Image Parameters
Consider the following diagram for a video field:
EAV SAV EAV
FOL +--------+-----------------------------------------+
| | |
| | |
| | |
| | |
| | Vertical Ancilliary Data (VANC) |
| | Blanking region including VITC,CC |
| | |
FAL | +-----------------------------------------+
| H A D | VL_OFFSET (0,0) |
| o n a | |
| r c t | |
| i i a | Active Video |
| z l | |
| o l | |
| n i | |
| t a | |
| a r | |
| l y | |
| (HANC) | VL_SIZE |
LAL | +-----------------------------------------+
| | Blanking region |
SOFC +--------------------------------------------------+
EAV - end of active video
SAV - start of active video
FOL - first output line
FAL - first active line
LAL - last active line
SOFC - start of field count
The data contained within the area labeled "Active Video" is the default
of which data is transferred to and from memory. But the hardware and
video driver allow the transfer to include most all the portion of the
"hidden" video, or the Horizontal and/or Vertical Ancilliary Data
(HANC/VANC).
Note that these controls are all "Path Controls".
VL_ORIGIN "origin" (VL_SRC/VL_SCREEN, VL_DRN/VL_MEM) path (x,y)
Used on the screen capture device to specify the origin of the capture
area. For Video input, the VL_ORIGIN can be used to specify a "black
fill" region.
Page 12
mvp(3dm)mvp(3dm)
VL_OFFSET "offset" (VL_ANY/VL_MEM) path (x,y)
Used on the memory node specify the upper left corner of the active video
region. For input, the area to the left and above the VL_OFFSET is
removed. For output, the same region is filled with "black".
Limitations of the value of VL_OFFSET are that the resultant offset must
be on a 2 pixel boundary. In addition, the following limits are imposed:
VL_TIMING Minimum VL_OFFSET
--------------------------
VL_TIMING_525_CCIR601 -134, -15
VL_TIMING_625_CCIR601 -140, -21
VL_TIMING_525_SQ_PIX 0, -15
VL_TIMING_625_SQ_PIX 0, -21
VL_SIZE "size" (VL_ANY/VL_MEM) path (x,y)
Used on the memory nodes to specify the lower right corner of the active
video region (VL_OFFSET + VL_SIZE == lower right corner). For input, the
area to the right and below this corner is removed. For output, the same
region is filled with "black".
VL_SIZE has a default according to the following table:
VL_TIMING VL_SIZE
-----------------
VL_TIMING_525_CCIR601 720, 243
VL_TIMING_625_CCIR601 720, 288
VL_TIMING_525_SQ_PIX 640, 240
VL_TIMING_625_SQ_PIX 768, 288
The actual size is affected by VL_ZOOM and VL_ASPECT (see VL_ASPECT
below), though both of these are defaulted to 1,1.
If the VL_CAP_TYPE ("fieldmode") is VL_CAPTURE_INTERLEAVED, then the
vertical or "y" size is doubled.
Limitations of the value of VL_SIZE are that the resultant size must be
on a 2 pixel boundary and the number of bytes to be transferred must be a
multiple of 8.
In addition, there is a limit to the number of pixels that may be
captured:
VL_TIMING Maximum VL_SIZE - VL_OFFSET
----------------------------
VL_TIMING_525_CCIR601 856, 261
VL_TIMING_625_CCIR601 860, 311
VL_TIMING_525_SQ_PIX 778, 261
Page 13
mvp(3dm)mvp(3dm)
VL_TIMING_625_SQ_PIX 934, 311
VL_ZOOM "zoom" (VL_ANY/VL_MEM) path (n,d)
Specifies the decimation of the input video to some fraction of it's
original size. Scaling from 1/1 downto 1/256 is available with the
actual increments being:
256 ... 1
---------
256
The actual zoom value is affected by VL_ASPECT (see next section).
Note that this control is only available on the VL_DRN/VL_MEM (input)
node.
VL_MVP_ZOOMSIZE "zoomsize" (VL_ANY/VL_MEM) path (x,y)
Specifies the decimation of the input video to some fraction of it's
original size and is independently zoomable in the X and Y directions.
The supplied x,y is used as a guideline to obtain the desired size and
VL_SIZE should be used to get the actualy size of the incoming video.
VL_ASPECT "aspect" (VL_ANY/VL_MEM) path (n,d)
VL_ASPECT is used to modify the input size to compensate for the aspect
distortion caused by capturing fields only. The values are 1,1 (default)
and 1,2. The effect on the VL_ZOOM is:
X SIZE = VL_SIZE.X * VL_ZOOM * VL_ASPECT
Y SIZE = VL_SIZE.Y * VL_ZOOM
X OFFSET = VL_OFFSET.X * VL_ZOOM * VL_ASPECT
Y OFFSET = VL_OFFSET.Y * VL_ZOOM
VL_CAP_TYPE "fieldmode" (VL_ANY/VL_MEM) path (int)
VL_CAPTURE_INTERLEAVED
This captures or sends buffers that contain both the odd (F1) and even
(F2) fields interlaced in memory. A side effect of changing from "non-
interleaved" to "interleaved" is that the VL_RATE will be halved.
VL_CAPTURE_NONINTERLEAVED
This captures or sends buffers that contain only one field each but are
transferred in pairs keeping the odd (F1) and even (F2) field of a
picture together. A side effect of this characteristic, if a transfer
Page 14
mvp(3dm)mvp(3dm)
error occurs in the second field, then the first is not transferred.
In addition, VL_RATE is effective on a pair of fields, though it is still
interpreted as a field rate. What this means is that if a field is to be
dropped because of the effects of VL_RATE, then both fields are dropped.
Also, changing from "interleaved" to "non-interleaved" causes the VL_RATE
to be doubled.
VL_CAPTURE_FIELDS
This captures or sends buffers that contain only one field each and are
tranferred individually. Since these are seperate fields then VL_RATE is
effective on individual fields, and a single field may be dropped.
Also, changing from "interleaved" to "fields" causes the VL_RATE to be
doubled.
VL_CAPTURE_EVEN_FIELDS
VL_CAPTURE_ODD_FIELDS
This captures only the even (F2) or odd (F1) fields. For output the
field is transferred during both field times.
VL_PACKING "packing" (VL_ANY/VL_MEM) path (int)
"rgba_8888" VL_PACKING_ABGR_8
This is actually RGBA format in memory and is the native OpenGL pixel
format.
"abgr_8888" VL_PACKING_RGBA_8
This is actually ABGR format in memory, with the alpha being supplied by
the alpha register. These are compatible with Iris GL as well as VINO
and Galileo/IndyVideo.
"uyvy_422_8" VL_PACKING_YVYU_422_8
This is actually UYVY in memory (Cb0 Y0 Cr0 Y1), 8 bits per component.
"uyvy_422_10" VL_PACKING_UYVY_422_10
This is actually UYVY in memory (Cb0 Y0 Cr0 Y1) with 10 bits per
component left justified in 16 bit words.
"vyua_4224_8" VL_PACKING_AUYV_4444_8
This is actually VYUA in memory (Cr0 Y0 Cb0 A0 Cr0 Y1 Cb0 A1) with 8 bits
per component and is compatible with the 4:4:4:4 format.
Page 15
mvp(3dm)mvp(3dm)
"argb_1555" VL_PACKING_RGBA_5551
This is a 16 OpenGL format laid out in memory as A(1 bit), R(5 bits), G(5
bits), and B(5 bits).
VL_SYNC "sync" (VL_DRN/VL_VIDEO) path (int)
The VL_SYNC selects the type of sync used for video output. The choices
are:
"Internal" VL_SYNC_INTERNAL
The timing for the output is generated using an internal oscillator
appropriate for the timing required (NTSC or PAL).
"Genlock" VL_SYNC_GENLOCK
The timing for the output is "genlocked" to the VL_SYNC_ SOURCE.
VL_SYNC_SOURCE "sync_source" (VL_DRN/VL_VIDEO) path (int) VL_SYNC_SOURCE
selects which sync source is used when VL_SYNC is set to VL_SYNC_GENLOCK.
The values for VL_SYNC_SOURCE are:
"External", MVP_SYNC_SOURCE_EXT
"SVideo/Composite", MVP_SYNC_SOURCE_AB
"Camera/Digital Video", MVP_SYNC_SOURCE_CD
VL_LAYOUT "layout" (VL_ANY/VL_MEM) path (int)
"Linear" VL_LAYOUT_LINEAR
The video pixels are arranged in memory in a "linear" fashion.
"Graphics" VL_LAYOUT_GRAPHICS
The video pixels are arranged in memory in a "pbuffer" fashion that is
compatible with the O2 OpenGL.
"Mipmap" VL_LAYOUT_MIPMAP
The video pixels are arranged in memory in a "texture" or "mimmapped"
fashion that is compatible with the O2 OpenGL.
MVP Signal Quality Controls
VL_BRIGHTNESS
VL_CONTRAST
VL_H_PHASE
Page 16
mvp(3dm)mvp(3dm)
VL_HUE
VL_SATURATION
VL_RED_SETUP
VL_GREEN_SETUP
VL_GRN_SETUP
VL_BLUE_SETUP
VL_BLU_SETUP
VL_ALPHA_SETUP
VL_V_PHASE
Most of these controls have a user selection mechanism on the
videopanel(1). See mvp(7) for more details.
VL_SIGNAL "signal" (VL_DRN/VL_VIDEO) device & path (int)
VL_SIGNAL_BLACK
VL_SIGNAL_REAL_IMAGE
VL_SIGNAL_NOTHING
VL_SIGNAL_COLOR_BARS
This control affects both the "quiescent" state of video output, as well
as active transfers to video output. When the channel is not in use,
then the output channel will output "black" or a passthru feed of the
active input "image". For the analog outputs (SVideo and Composite),
"colorbars" can also be selected.
During an active transfer, when the user application fails to deliver an
output image within the time required by the timing standard, then the
driver selects what to do based on the signal setting. if the signal is
set to "black" (or "colorbars"), the output will be black causing
flashing on the output. This is useful to determine if the application
is not "keeping up" with the output.
If the signal is set to "image", then the driver will repeat the previous
two fields. This requires that the driver actually hold onto these two
buffers, releasing them when two more fields are delivered from the user.
This increases the overall number of buffers required for processing by 1
for INTERLEAVED or NONINTERLEAVED capture modes.
VL_FLICKER_FILTER "flicker_filter" (VL_SRC/VL_SCREEN) device (t,f)
Enables or disables the "flicker" filter for screen capture.
VL_DITHER_FILTER "dither_filter" (VL_SRC/VL_VIDEO) device (t,f)
Enables or disables the "dither" filter on video input.
VL_NOTCH_FILTER "notch_filter" (VL_DRN/VL_VIDEO) device (t,f)
Enables or disables the "notch" filter on video output.
Page 17
mvp(3dm)mvp(3dm)MVP Specific Controls
These controls are in the <dmedia/dev_mvp.h> header file.
VL_MVP_OUTPUT_ENABLE
This controls what part of the output video is routed to which output
jacks. It only really matters for those formats which include an Alpha
component though it can also be used to effect a software "passthru"
switch.
"Pixels/Pixels" Output pixels to both primary (analog/primary D1) and
secondary (digital/secondary D1) jacks.
"Pixels/Alpha" Output pixels to the primary (analog/primary D1) jack and
alpha to the secondary (digital/secondary D1) jack.
"Alpha/Pixels" Output alpha to the primary (analog/primary D1) jack and
pixels to the secondary (digital/secondary D1) jack.
"Alpha/Alpha" Output alpha to both primary (analog/primary D1) and
secondary (digital/secondary D1) jacks.
"Passthru/Passthru" Output the input selected by the genlock source to
both primary (analog/primary D1) and secondary (digital/secondary D1)
jacks.
MVP Buffer and Event Routines
The buffer routines allocate a pool to use during the video transfer and
the event routines are used to control the transfer. Note that these
routines are only valid for paths that are not classified as "DevPath"'s.
In release 6.3 there was added a new Digital Media Buffering API (termed
"dmBuffers") that facilitates exchanging buffers with other media
libraries in an efficient manner. The previous Digital Media Ring Buffer
API (termed "DMRB") is compatible with the old VL and is described first.
Since each API has some unique Event handling routines, they are also
included here.
Note: In release 6.4, there is a further extension of the Digital Media
Buffer interface that is somewhat different than the one described here
and is discussed in documention available with that release. Release 6.5
is scheduled to include all the video platforms in a single release with
a common Digital Media Buffer interface.
MVP Buffer and Event DMRB Routines
vlGetTransferSize(VLServer, VLPath) The transfer size in bytes of each
buffer is returned as the function value.
Note that the transfer size may change if any controls are changed. If
Page 18
mvp(3dm)mvp(3dm)
the controls are expected to be changed during the transfer, then the
controls should be set at their maximum anticipated values before
requesting the transfer size.
vlCreateBuffer(VLServer, VLPath, VLNode, numFrames) A buffer pool is
allocated large enough contain numFrames number of frames and is returned
as the function value. A return value of NULL indicates the request
could not be satisfied and vlErrno is set to the error code.
Note that the buffer size requirements may change if any controls are
changed. If the controls are expected to be changed during the transfer,
then the controls should be set at their maximum anticipated values
before the buffer pool is created.
vlDestroyBuffer(VLServer, VLBuffer) The buffer pool created by vlCreate
buffers is removed from the system.
vlRegisterBuffer(VLServer, VLPath, VLNode, VLBuffer) The buffer allocated
with vlCreateBuffer is registered to this video path. Note that in MVP
only one video buffer may be registered to a path, and that a buffer may
only be registered to one path.
vlDeregisterBuffer(VLServer, VLPath, VLNode, VLBuffer) The buffer is
disassociated with the video path.
vlBufferAdvise(VLBuffer, usageInfo) This advises the video system as to
the anticipated usage of the buffer. If the buffer will be accessed by
the user program using the CPU, then VL_BUFFER_ADVISE_ACCESS should be
specified. Otherwise, VL_BUFFER_ADVISE_NOACCESS should be specified
which will greatly reduce the overhead of dealing with the CPU cache.
vlBufferGetFd(VLBuffer) An FD is returned as the function value that can
be used in a select call to indicate when there is space available in the
buffer for paths that are outputting video.
vlBufferDone(VLBuffer) The "buffer done" bit is checked which normally
indicates that the sending side has finished transferring.
vlBufferReset(VLServer, VLBuffer) The "buffer done" bit is reset.
vlGetNextFree(VLServer, VLBuffer, size) An empty buffer is allocated from
the pool and it's "info" pointer is returned to the caller. NULL
indicates that there are no empty buffers at the moment.
(See vlGetActiveRegion to obtain a pointer to the data area.)
vlPutValid(VLServer svr, VLBuffer buffer) The oldest buffer obtained by
the vlGetNextFree call is sent to the other side of the path.
Normally these are buffers that are filled with data for output, but they
could also be empty buffers sent to the video capture to be filled with
data. (Note that this is NOT required in that if there are no
Page 19
mvp(3dm)mvp(3dm)
preallocated buffers sent the video driver will allocate one if there is
space in the buffer pool.)
vlGetNextValid(VLServer, VLBuffer) An "info" pointer to the next buffer
containing a valid image is returned to the user. Any intervening non-
data events are discared during the processing of this function.
NULL indicates that there are none available at the moment.
(See vlGetActiveRegion to obtain a pointer to the data area.)
vlGetLatestValid(VLServer, VLBuffer)
An "info" pointer to the last buffer containing a valid image is returned
to the user. All previous data buffers (and non- data events) are
discarded during the processing of this function.
NULL indicates that there are none available at the moment.
(See vlGetActiveRegion to obtain a pointer to the data area.)
[Note that this routine was used to get around a problem in the old VL
video daemon in that there was not real way to determine the number of
buffers available for each data event. This is no longer true with
DVL/MVP and this function could easily be made obsolete with correct
programming of the VL program. (See EXAMPLES below)]
vlPutFree(VLServer, VLBuffer) The oldest buffer that was obtained with
vlGetNextValid or vlGetLatestValid is returned to the buffer pool.
vlGetActiveRegion(VLServer, VLBuffer, VLInfoPtr) This will return a
pointer to the active data area.
vlGetDMediaInfo(VLServer svr, VLBuffer buffer, VLInfoPtr info)
This will return a pointer to the DMedia Info structure. See
/usr/include/sys/dmcommon.h for more details.
vlGetImageInfo(VLServer svr, VLBuffer buffer, VLInfoPtr info)
This will return a pointer to the Image Info structure. See
/usr/include/sys/dmcommon.h for more details.
The following routines are also ONLY available with the DMRB:
Note that there are two ways to control the VL transfer with the DMRB.
The first being that you can use the FD returned by vlGetFD in a select
call (with of course other FD's the program may be monitoring) that
sleeps until there is an "event" or some required processing wakes up the
select call.
The alternative is simliar to the X Server in that you can register which
Page 20
mvp(3dm)mvp(3dm)
function you want called when specific events on specific paths occur.
In addition, you can register handlers for any other FD's the application
may be interested in. Then the application program basically relinquishs
control to vlMainLoop() and processes all subsequent "events" or process
requests via callbacks.
The first method uses:
vlGetFD(VLServer)vlConnectionNumber(VLServer) Get an FD representing the
server and on which the user may select on to indicate when events are
ready to be processed. For video capture this includes data and control
events. For video output this includes control events only.
vlBufferGetFd(VLBuffer) Get an FD representing the buffer and that wakes
up when there is space available in the buffer. This is handy when the
user app is outputting video and wants to wake up when space has been
freed up.
vlNextEvent(VLServer, VLEvent *) Get the next event off the queue after
the FD returned by vlGetFD causes the select to wakeup.
And the second method uses (note that vlNextEvent is also used in the
"handler" defined with vlAddCallback).
vlAddCallback(VLServer, VLPath, VLEventMask, VLCallbackProc, void *) Add
VLCallbackProc to handle VLEventMask events on the path specified.
vlRemoveCallback(VLServer, VLPathpath, VLEventMask, VLCallbackProc, void
*) Remove the callback procedure.
vlRemoveAllCallbacks(VLServer, VLPathpath, VLEventMask) Remove all
callback procedures.
vlCallCallbacks(VLServer, VLEvent *) Call all callback procedures that
have expressed an interest in the specified event.
vlRegisterHandler(VLServer, fd, VLEventHandler, VLPendingFunc, void *)
Register VLEventHandler (using VLPendingFunc to determine if an event is
pending) to service device on "fd" when it becomes active during a
select.
vlRemoveHandler(VLServer, fd) Remove the handler associated with the
device on "fd".
vlMainLoop(void) After setting up the required handlers and callbacks,
the user is requesting that the VL take over waiting for events and
simply call the event handlers when appropriate.
Other routines that may be useful in either method are:
vlPending(VLServer) Check whether there are pending events.
Page 21
mvp(3dm)mvp(3dm)
vlCheckEvent(VLServer, VLEventMask, VLEvent *) Check if any events listed
in the VLEventMask is queued, and if so return it.
vlPeekEvent(VLServer, VLEvent *) Look at the next event on the queue
without dequeuing it.
MVP Digital Media Buffer Routines
vlDMPoolGetParams(VLServer, VLPath, VLNode, DMparams *) Get the
parameters associated with a video path. Note that all pertinent
controls must have been set prior to this call. If the user program is
expecting to change any controls that affect the size of the buffer, then
the controls should be set to their maximum values prior to this call.
vlDMPoolRegister(VLServer, VLPath, VLNode, DMbufferpool) Register a DMS
Buffer Pool to this path. Only one buffer pool may be registered to any
one path.
vlDMPoolDeregister(VLServer, VLPath, VLNode, DMbufferpool) Disassociate a
DMS Buffer Pool with this path.
vlDMBufferSend(VLServer, VLPath, DMbuffer) Send a DMS buffer to the other
side of the stream.
vlPathGetFD(VLServer, VLPath, int *ret_fd) Get an FD associated with the
path for use with a select call. This FD will wake up when there are
events to be received on the video stream. This includes data and
control events for video capture and control events for video output.
vlEventRecv(VLServer, VLPath, VLEvent *) Receive any events pending for
this path after the FD from vlPathGetFD causes the select to wakeup.
vlEventToDMBuffer(VLEvent *, DMbuffer *) Get the pointer to a DMS buffer
associated with a VL event.
MVP Event Common API's RoutinesVLEventToMask(VLevent) The VL event is converted to a VLEventMask value.
vlSelectEvents(VLServer, VLPath, VLEventMask) Select which VL events the
user program wants to receive.
vlEventToName(int type) Translate an event into an ascii string.
vlServerProtocolVersion(VLServer) Get the version of the VL protocol.
vlServerProtocolRevision(VLServer) Get the revision of the VL protocol.
vlServerVendorRelease(VLServer) Get the release number of the VL
protocol.
Page 22
mvp(3dm)mvp(3dm)vlServerString(VLServer) Get the name of the video server.
MVP Audio/Video Synchronization Routines
These routines let you compute the Unadjusted System Time (UST) for any
field or frame in your transfer. They are only supported when VL_RATE is
the maximum rate (50/1 or 60/1) for the current video timing.
vlGetFrontierMSC(VLServer, VLPath, VLNode) vlGetFilled(VLServer, VLPath,
VLBuffer buffer) vlGetPathDelay(VLServer, VLPath, VLNode, VLPort,
VLNode2, VLPort2) vlGetUSTMSCPair(VLServer, VLPath, VLNode, VLPort,
VLNode, USTMSCpair*) vlGetUSTPerMSC(VLServer, VLPath, VLNode)
These routines are described in other Video Library man pages.
Because all mvp paths involve memory, mvp does not implement
vlGetPathDelay().
Note: The vlGetFrontierMSC(3dm) manpage has the following statement
under the CAVEATS section:
For some VL devices, there is a short initial period (up to ten
field times) in the lifetime of a transfer during which no
frontier MSC is available. This period begins when the
application calls vlBeginTransfer(3dm) and ends when the device
clocks in or out its first media stream sample from the
application's VLBuffer. An attempt to call
vlGetFrontierMSC(3dm) during this period will block the
application until the end of the period, when a valid frontier
MSC is available.
Previous to patch2836 (Irix 6.3) and the Irix6.5 version of the MVP
driver, an attempt to access an "early" Frontier MSC would return an
unreliable MSC until the video device had actually transferred at
least 2 fields or a frame. In patch2836 and Irix 6.5, the driver
will now correctly wait until the Frontier MSC is "valid". To
enable this new behaviour, you must set the systune variable
mvpearly_frontiermsc to a "0". [See systune(1M) for more details.]
After this is done, some applications may seem to hang, or act
strangely if they are not programmed correctly.
MVP Transfer Routines
vlBeginTransfer(VLServer, VLPath, count, VLTransferDescriptor *) Initiate
a data transfer. The following modes are supported:
VLTransferDescriptor Modes
VL_TRANSFER_MODE_CONTINUOUS
The transfer is initiated to be a continuous transfer and the user
Page 23
mvp(3dm)mvp(3dm)
program is resumed after startup.
VL_TRANSFER_MODE_DISCRETE
The transfer is initiated to be a discrete transfer, usually of some
number of frames. The user program is stalled while the transfer is in
progress and is resumed when all the frames have been transferred.
VL_TRANSFER_MODE_AUTOTRIGGER
The transfer is initiated upon some trigger event which is a subset of
the VL events. Currently, VLDeviceEvent is the only trigger event
supported by MVP.
vlEndTransfer(VLServer, VLPath) The continuous transfer started with
vlBeginTransfer is stopped.
MVP Events
VLStreamBusy The stream is already locked by someone else.
VLStreamPreempted The stream was grabbed by another path. Use
stream_usage == VL_LOCK to prevent this.
VLAdvanceMissed The trigger time has already past.
VLStreamAvailable The stream has been released by another using path.
VLSyncLost Sync isn't being detected. This happens for example, when the
user pulls the video cable out.
VLStreamStarted - Stream started delivery
VLStreamStopped - Stream stopped delivery
These are primarily for those paths in which there is a direct connection
between video nodes and there are no individual transfer events. MVP
does send these though.
VLSequenceLost A Field/Frame dropped. This means that "for some reason"
the driver missed a frame. You can also check using the MSC values.
(Though output is a little trickier to check).
VLControlChanged A Control has been changed by either VCP or some other
program.
VLTransferComplete A transfer has been completed. For input to memory,
there is also a data buffer associated with the event.
VLTransferFailed A transfer has failed. This tells you that there's
trouble and won't be getting anything more on this path.
VLEvenVerticalRetrace - A Vertical Retrace event
VLOddVerticalRetrace - A Vertical Retrace event
Page 24
mvp(3dm)mvp(3dm)
VLFrameVerticalRetrace - A Vertical Retrace event
Can be used on some devices for timing reasons. MVP supplies these, but
only if a transfer is in progress.
VLDeviceEvent The GPI input signal has triggered.
VLDefaultSource Default Source Changed. This means the user has selected
a different input and VL programs may change their input to match, if
programmed to do so.
VLControlRangeChanged The range of a control has changed. This might
occur, for example, when the timing has been changed a new range for
VL_SIZE might become available.
VLControlPreempted This path's usage of the controls has been preempted
by another path.
VLControlAvailable The other path has relinquished the controls and they
are now again available.
GPI General Purpose Interrupt
(For the un-initiated, GPI is NOT a pulse. It's a state and asserting a
GPI means changing the state from low to high or high to low.)
Basically, VLControlValue union is extended to support transfer_trigger,
gpi_out (for output triggering) and gpi_state (for explicitly setting and
querying the GPI lines) controls.
1) transfer_trigger control can be used to setup the trigger control for
beginning the transfer. The triggers supported in MVP is GPI only.
2) gpi_out control is used to program the gpi_out line. Two conditions
are supported for asserting the GPI line : transfer_start, transfer_stop
You can have multiple trigger conditions outstanding.
To clear the triggers, use gpi_state control with clear flag. All
outstanding trigger controls on the particular line are cleared.
3) gpi_state control is used to set/get the state of gpi lines. The
states are ON, OFF, PULSE (transition for 1 field time) and clear.
VL API is being enhanced to support GPI as a device independent
interface. GPI triggers are supported in three vlSetControl()
interfaces:
The union VLControlValue is extended to support transfer_trigger, gpi_out
(for output triggering) and gpi_state (for explicitly setting and
querying the GPI lines) controls.
1) transfer_trigger (VL_TRANSFER_TRIGGER)
Page 25
mvp(3dm)mvp(3dm)
This control can be used to setup the triggering for beginning the
transfers on a path. This control is supported on Video nodes.
The following code illustrates a GPI based trigger transfer setup,
VLControlValue val;
val.xfer_trigger.triggerType = VL_TRIGGER_GPI;
val.xfer_trigger.value.instance = <which GPI input line>
vlSetControl(svr,path,VL_TRANSFER_TRIGGER,&val);
2) gpi_out (VL_GPI_OUT_MODE)
This control is used to program the gpi_out line. Two conditions are
supported for asserting the GPI line: transfer_start, transfer_stop.
You can have multiple trigger conditions outstanding.
The following code segment illustrates a setup for the gpi_out line 1 to
toggle at the beginning and end of transfer.
VLControlValue val;
/* make sure the GPI line is high */
val.gpi_state.gpi = VL_GPI_OUT;
val.gpi_state.instance = <which GPI line>;
val.gpi_state.state = VL_GPI_OFF;
vlSetControl(svr,path,VL_GPI_STATE,&val);
/* transfer start */
val.gpi_out.condition = VL_GPI_OUT_XFER_START;
val.gpi_out.instance = <which GPI output line >;
val.gpi_out.state = VL_GPI_ON;
vlSetControl(svr,path,VL_GPI_OUT_MODE,&val);
/* transfer stop */
val.gpi_out.condition = VL_GPI_OUT_XFER_STOP;
val.gpi_out.instance = <which GPI output line >;
val.gpi_out.state = VL_GPI_OFF;
vlSetControl(svr,path,VL_GPI_OUT_MODE,&val);
To clear the triggers, use gpi_state control with clear flag. All
outstanding trigger controls on the particular line are cleared.
3) gpi_state (VL_GPI_STATE)
This control is used to query the state of the input_gpi lines and
set/get the state of output_gpi lines. The states are ON, OFF,
PULSE(transition for 1 field time) and CLEAR.
Page 26
mvp(3dm)mvp(3dm)
This code fragment clears all output triggers on the specified line:
VLControlValue val;
val.gpi_state.gpi = VL_GPI_OUT;
val.gpi_state.instance = <which GPI line>;
val.gpi_state.state = VL_GPI_CLEAR;
vlSetControl(svr,path,VL_GPI_STATE,&val);
See /usr/include/dmedia/vl.h for specific details on the various controls
and settings.
Programming Exammple for Selecting Nodes
Future O2 may (and other SGI systems usually) have different video input
and output capabilities. By checking the device list with
vlGetDeviceList(), the user program can discover which video connections
exist, without having to reprogram their applications for each video
interface.
The following routine shows one method of doing this.
/*
* getVideoInputNode example
*/
#include <dmedia/vl.h>
#include <stdio.h>
#define MAX_NUMBER_NODES 32
VLNode
getVideoInputNode( VLServer svr )
{
int dn; /* device number */
int dnn; /* device's node number */
int nn; /* node table node number */
VLDevList devl;
VLDevice *dev;
VLNodeInfo *ni, *nt[ MAX_NUMBER_NODES ];
int selection = -1;
if( vlGetDeviceList( svr, &devl ) == -1 ) {
vlPerror( "vlGetDeviceList" );
return -1;
}
printf( "0elect one of the following video inputs0 );
printf( "0 <default input>0 );
/* for each device */
for( dn = 0, nn = 0, dev = devl.devices;
Page 27
mvp(3dm)mvp(3dm)
dn < devl.numDevices;
dn++, dev++ ) {
/* for each node on each device */
for( dnn = 0, ni = dev->nodes;
dnn < dev->numNodes && nn < MAX_NUMBER_NODES;
dnn++, ni++ ) {
/* if it's an input video or screen node,
* then list it */
if( ni->type == VL_SRC &&
( ni->kind == VL_VIDEO ||
ni->kind == VL_SCREEN ) ) {
printf( "%d %s0, nn + 1, ni->name );
nt[ nn++ ] = ni;
}
}
}
/* get answer into integer "selection" */
printf( "> " ); fflush( stdout );
scanf( "%d", &selection );
/* if selection within range */
if( 0 < selection && selection <= nn ) {
ni = nt[ selection - 1 ];
return vlGetNode( svr, ni->type, ni->kind, ni->number );
}
/* user didn't decide - so use default source */
return vlGetNode( svr, VL_SRC, VL_VIDEO, VL_ANY );
}
main( int ac, char **av )
{
VLServer svr = vlOpenVideo( "" );
VLNode vidNode = getVideoInputNode( svr );
VLNode memNode = vlGetNode( svr, VL_DRN, VL_MEM, VL_ANY );
VLPath path = vlCreatePath( svr, VL_ANY, vidNode, memNode );
if( vlSetupPaths( svr, &path, 1, VL_SHARE, VL_SHARE ) < 0 ) {
vlPerror( "error seting up video path" );
exit( 1 );
}
printf( "0ideo path setup0 );
}
Page 28
mvp(3dm)mvp(3dm)ERRORS
The standard VL error codes are applicable:
VLSuccess - everything's okay
VLBadRequest - bad request code
VLBadValue - int parameter out of range
VLBadPath - parameter not a path
VLBadNode - parameter not a node
VLBadAtom - parameter not an atom
VLBadDevice - parameter not a device
VLBadControl - parameter not a control
VLBadMatch - parameter mismatch
VLBadAccess - depending on context
VLBadAlloc - insufficient resources
VLBadIDChoice - choice not in range or already used
VLBadName - font or color name doesn't exist
VLBadLength - Request length incorrect
VLBadIoctl - ioctl failed in the server
VLBadImplementation - server is broken
VLPathInUse - Path is in exclusive use
VLBadServer - Server parameter is invalid
VLBadBuffer - Buffer invalid
VLBadSize - Buffer size invalid
VLNotEnoughResident - we don't have enough resident memory
VLBufferTooSmall - the buffer allocated is too small
VLValueOutOfRange - the value is out of range (for controls)
VLSetupFailed - SetupPath of failed
VLBadWinAlloc - Insufficient hardware screen space
VLInputsNotLocked - Video input sources cannot be locked
SEE ALSOVLINTRO(3dm), O2Video(7)
Page 29
