mvp(3dm)
mvp - Multiport Video Processor for the O2 system
As shipped in IRIX 6.5. First release of IRIX 6.5.
NAME mvp - 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. * 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. 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 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. 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 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. 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. 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 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: 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. 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. 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 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 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. "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 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. 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 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 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 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. 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 Routines VLEventToMask(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. 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 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 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) 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. 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; 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 ); } 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 ALSO VLINTRO(3dm), O2Video(7)