Chapter 2: Xlib Extension

If you are interested in building custom video widgets and applications for Parallax hardware, Parallax provides an extension to Xlib that allows full access to Parallax Graphics video hardware capabilities. Our Xlib extension supports a ful range of video capabilities: video input with control of input settings, color, image size, etc., video output to a VDR or other external device, and real-time JPEG compression and decompression of video for videoconferencing and movie capture and playback. This extension is available to developers on Sun Solaris and HP-UX platforms. This chapter includes:
Overview
Source Code for Applications
Source-Code for Example Programs
Functions Required to Initialize X Windows
Include and Library Files
Usage, Makefile, and Imakefile Support

Core Functions
JPEG Functions

Using Shared-Memory for JPEG Compression
Deallocating Shared Memory

Utility Functions

Overview

The Parallax video extension to Xlib supports the development of video widgets and applications for Parallax XVideo, PowerVideo, and MultiVideo cards. With this extension, we provide two basic sets of functions, plus some utilities:

Core functions support the initialization, color-manipulation, and scaling of X windows or bounded regions on the display for Parallax video inputs and outputs

JPEG functions support the compression and decompression of Parallax video images and 24-bit graphics for display, for storage to disk, for direct-memory access over the network, or for caputres to MovieTool format JPEG movie files.

Utility funcitons (available only in recent software releases) support multiple Parallax video cards in one workstation, sleep, and finding a TrueColor visual.

NOTE: This extension offers an interface to the features and functionality of Parallax video hardware and is intended to complement--but not replace--other video interfaces to X (such as xv).

Source Code for Applications

Parallax Graphics' applications VideoTool, MovieTool, and for users of some platforms, MovieCat and RTMovieTool, provide examples of the capabilities that can be supported by the Parallax Graphics Video Development Environment and the Parallax video server and driver software. Before you start developing your own video application, you may want to look at these applications to get ideas for building your own applications.

The applications are fully tested and released.

The source files for the application programs are located in $PARALLAX_HOME/src in the following sub-directories:

Table 2-1 Application locations within $PARALLAX_HOME/src:

Application	Summary	Source File Location
MovieTool	Captures and plays back MovieTool format movies with audio in real-time.	/motif/MovieTool
VideoTool	Displays live video (up to two simultaneous for XVideo), catures still images, adjusts color setitngs and image size, sends video out to external devices for XVideo.	/motif/VideoTool

Note: These motif applications are not available for SunOS 4.1.x/X11R5

Source-Code for Example Programs

To demonstrate how to use the Xlib extensions, we provide simple source-code example programs that can be run from the UNIX commmand line.

These sample programs are not as carefully built as the application programs, but do provide useful brief exmaples of how to use the Parallax development tools and hardware capabilities.

To use the sample programs:

1. Look for a program that has some functionality you want to use (see summaries below). See how the program works (Multimedia Users Guide, Appendix C) and try out the program.

2. Look at the source code for the sample program.

The source files for sample programs are located in $PARALLAX_HOME/src in the following sub-directories:

Table 2-2 Sample program locations within $PARALLAX_HOME/src:

Sample Program	Summary	Source File Name and Location
govTest, govLogo, govLogo2	Sun Solaris 2.5, framebuffers only: Show graphics over video capabilities. govTest brings up a stationary red dot over video. govLogo and govLogo2 bring up the Parallax Graphics logo bouncing around over video.	/xlib/example/gov*.c
makeMovie	Sun Solaris, framebuffers only: Captures, compresses, and saves a MovieTool format movie with audio in real-time (NTSC, PAL, or SECAM source).	/xlib/MakeMovie
playMovie	Sun Solaris, framebuffers only: Plays back (opens, decompresses, and displays) a pre-recorded MovieTool format movie with audio.	/xlib/PlayMovie
rtvPlay	Sun Solaris 2.5, framebuffers only: Plays back (opens, decompresses, and displays) a pre-recorded RTMovieTool format movie with audio.	/xlib/example/rtvPlay.c
rtvRecord	Sun Solaris 2.5, framebuffers only: Captures, compresses, and saves an RTMovieTool movie with audio in real-time (NTSC or PAL video source).	/xlib/example/rtvRecord.c
xlib_test	Opens a video window and displays live video (from an NTSC video source connected to the cable labeled "Video In Composite 1").	/xlib/example/xlib_test.c

Note: Binary files for these programs are located in "$PARALLAX_HOME/bin".
Note: If you are using SunOS 4.1.x and X11R5, look for sample programs in the location, "$PARALLAX_HOME/X11R5/src/xlib/example".

Functions Required to Initialize X Windows

The following functions are required to initialize X windows for Parallax video input and/or output, and should be executed in the order shown:

Table 2-3 Functions required to initialize X windows

Step	Function
1st	XPlxQueryConfig -- required in every Parallax video program that uses the XPlx extension. This function calls a low-level hardware library of routines to determine which Parallax product is installed, then creates an appropriate plx_IO structure (as defined in the XPlxExt.h include file).
2nd	XPlxVideoInputSelect -- required in Parallax video programs that display live video in an X window. and/or XPlxVideoOutputSelect--required in Parallax video programs that export a bounded reion of the display as video to a connected video output device. These functions specify parameters for the selection of a Parallax video I/O channel and for the processing of a video input signal--or the generation of a video output signal--based on the signal standard, A/D signal processing format, and color-conversion type.
3rd	XPlxQueryVideo -- required to validate the parameters offered with XPlxVideoInputSelect and, if valid, initalize video input to an X window on the display. This function checks the currently specified input channel to determine if a vlid signal sync is present. If a signal sync is found, this function returns TRUE to the plx_* structure, along with the standard, format, type, and other characteristics of the incoming signal (as defined in XPlxExt.h). (If the characteristics of the incoming signal are not valid for the currently selected channel, video will not display properly.)
4th	XPlxVideoTag--required to tab the graphics context of the X window for Parallax video framebuffer cards video input drawing operations. (Required only for framebuffer cards.) This function marks the graphics context of the window for a specified Parallax drawing operation. Three types of drawing operations are supported: 1-, 8-, or 24-bit graphics (PLX_GRAPHICS) or 24-bit video (PLX_VIDEO), or video override (PLX_VIDEO_OVR). This last operation overrides the clear screen event on window redraws so that the window continuously displays video and doesn't "flash black" on window moves or resizes

Note: The fourth step above (XPlxVideoTag) is only required for applications that support Parallax framebuffer cards (including cross-platform applications that support both overlay and framebuffer cards).

Once a video input window or output region is initialized on the display, other XPlx functions-- which change the characteristics or I/O state of an input window or output region on the X display-- can be exectured. Detailed reference information for each of these XPlx functions is provided in the next section, Core Functions.

Include and Library Files

Programs developed with the Xlib video API (XPlx functions) should include both the <XPlxExt.h> and <XPlxProtos.h> files--along with standard <stdio.h>, <X11/Xlib.h>, and other include files--and should be compiled with both the XPlx library file, libXPlx.a, and with libXv.a. For more details, please see Appendix A: Include and Library Files.

Note: If you are using Solaris 2.4 or earlier, you do not need to compile with libXv.a.

1. Add the appropriate include files to your application sourcefile:

#include <XPlxExt.h>

#include <XPlxProtos.h>

Usage, Makefile, and Imakefile Support

1. Makefile: If you are using a Makefile, add the applicable compiler command to your application Makefile:

Parallax software for Sun Solaris 2.5, H-P version 9.3, or later:

cc <sourcefile> -L$(PARALLAX_HOME)/lib -lXPlx -lXv -lXext -lX11 -lm

Parallax software for Sun Solaris 2.4 or earlier:

cc <sourcefile> -L$(PARALLAX_HOME)/lib -lXvid -lXext -lX11 -lm

Parallax software for HP-UX version 9.2 or earlier:

cc <sourcefile> -L$(PARALLAX_HOME)/lib -lXvid -lXv -lXext -lX11 -lm

Parallax software for Sun Solaris 1.x (SunOS 4.1.x) and X11R5 version 1.2:

cc <sourcefile> -L$(PARALLAX_HOME)/X11R5/lib -lXvid -lXext -lX11 -lm

Note: The user must set a site-specific environmental variable to successfully compile the makefiles. PARALLAX_HOME should point ot the directory where the VDE software is installed. For example: "setenv PARALLAX_HOME /opt/parallax"

Note: Motif users on the Sun platform: If you are developing a Motif applications using Parallax libraries and our imake file support, you must have the Motif distribution installed in "/opt/SUNWmotif" (Motif located here or linked to this location).

2. Imakefile for Parallax software version Solaris 2.5 or HP 9.3 or higher: If you are using an Imakefile, be sure that these lines are included in your application Imakefile:

INCLUDES = -I$(INCLUDESRC) -I$(PLXINCLUDESRC)


DEPLIBS = $(PlxDepLib) $(DEPEXTENSIONLIB) $(DEPXLIB)


LOCAL_LIBRARIES = $(PlxLib) $(XLIB)


SYS_LIBRARIES = $(SystemSpecific)

Note: Sample Imakefiles are provided in the same location as sample application source code. You can copy the Imakefile provided and modify it as needed.

3. ANSI-C: You must use an ANSI-C compiler to compile the source files included with your Video Development Environment.

For More Information For more details on the include library files, please see Appendix A: Include and Library Files. For a description of the Parallax variables that can be used in XPlx functions to hardcode and/or alter the behavior of video inputs and outputs, please see Appendix B: Parallax Video Variables. (These variables are defined in the plx_* data structures in the XPlxExt.h include file). For more information about the standard Xlib functions, see a manual such as the Xlib Reference Manual, published by O'Reilly and Associates, Inc.

Core Functions

The following pages describe the core functions that are defined in our Xlib extension library, libXPlx.a. These functions support the initialization, color-manipulation, and scaling of X windows or regions on the display for Parallax video inputs and outputs.

Function	Summary
XPlxGetImage()	Still Image: Gets an XImage from Parallax video memory; dumps the contents of a specified rectangle into an XImage structure (24-bit for framebuffer cards, 32-bit for overlay)
XPlxGetZoomFactor()	Zoom (video overlay cards only): Gets the current zoom factor for the video card associated with the specified window.
XPlxPutImage()	Still Image: Draws an XImage into the Parallax video memory
XPlxQueryConfig()	Query Hardware: Determines type of Parllax video card and builds appropriate input/output structure (to manage input/output drawables)
XPlxQueryVideo()	Video In: Queries the current input channel to look for valid sync; returns a structure that describes the signal (including a valid sync field)
XPlxScaleCopyArea()	Video In: Copies the contents fo a window and displays this as scaled video in a second window
XPlxSetVideoParameterString()	Special Effects (video framebuffer cards only): Offers a limited set of video modes provided by the Parallax avideo framebuffer cards (display video in black=and-white, etc.)
XPlxSetZoomFactor()	Zoom (video overlay cards only): Sets the zoom factor for the video overlay card attached to the specified window.
XPlxVideoInputSelect()	Video In: Sets digitization and display parameters for the video input signal (specifies which channel, standard, format, etc.).
XPlxVideoLive()	Video In: Displays unscales live video in a window
XPlxVideoOutputSelect()	Video Out: Outputs the contents of a specified region of the display as scaled video.
XPlxVideoScaleOutput()	Video Out: Outputs the contents of a specified region of the display as scaled video.
XPlxVideoSqueezeLive()	Video In: Displays scaled liver video in a window.
XPlxVideoSqueezeStill()	Still Image: Displays a scaled still frame of video in a window.
XPlxVideoStill()	Still Image: Displays an unscaled still frame of video in a window.
XPlxVideoStop()	Video In: Stops digitization and display of live video in a window.
XPlxVideoTag()	Graphics Context: (video framebuffer cards only) Sets up graphics context to tag pixels for a specified drawing operation.
XPlxVideoValueLoad()	Color Settings: Applies user-specified color settings (brightness, contrast, hue, saturation) to the current video window.
XPlxVideoValueQuery()	Color Settings: Returns the values of a window's current color settings
XPlxVideoValueRecall()	Color Settings: (framebuffer cards only) Sets the window's color settings (brightness, etc.) to those stored on the video card's NVRAM.
XPlxVideoValueSave()	Color Settings: (framebuffer cards only) Saves the current color settings as user preferences on the video card's NVRAM

XPlxGetImage()

Parallax software for Sun Solaris 2.5 and version 9.3 for HP or higher; Gets an XImage from Parallax video memory

Usage

XImage *XPlxGetImage(display, window, x, y, width, height, plane_mask, format)

Display *display;
Window window;
int x;
int y;
unsigned int width;
unsigned int height;
unsigned long plane_mask;
int format;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay();
window Specifies the window to get the data from.
x,y Specify the x and y coordinates of the upper-left corner of the rectangle, relative to the origin of the window (for current limitations, see second note on next page).
width, height Specify the width and height in pixels of the image.
plane_mask Specifies a plane mask that indicates which planes are represented in the image.
format Specifies the format for the image. We suggest you use ZPixmap.

Returns

The created image.

Description

XPlxGetImage() dumps the contents of the specified rectangle into a client-side XImage structure. On Parallax framebuffer cards (XVideo, XVideo-VIO, PowerVideo, MultiVideo Sun cards), the returned image has a 24-bit depth. On all Parallax video overlay cards (XVideo Xtra and H-P cards), the returned image has a 32-bit depth. This can present a problem because not all window servers can handle 32-bit images. If you want to display the resulting image using XPutImage(), you may want to change the depth from 32-bits to 24-bits.

When using XPlxGetImage() in Zoom 2x mode, be sure to specify a region that is 1/2 the actual window size (1/2 the width and 1/2 the height).

Note: For Parallax software releases Sun overlay (Xtra) 1.0 and 1.1 and H-P 9.3 and 10.10: Please make sure that you use another Parallax call before you use XPlxGetImage. If you use XPlxGetImage as the first call, it will not set up the internal structures correctly.

Note: For Parallax software releases Sun overlay (Xtra) 1.0 and 1.1 and H-P 9.3 and 10.10: For these same releases, XPlxGetImage supports only images with a 0,0 origin in the upper left corner of the source image, so it's not possible to get an image that is cropped to exclude the upper left corner of the source image with this call.

XPlxGetZoomFactor()

Parallax software for Sun Solaris 2.5 and version 9.1 for HP or higher (works for video overlay cards only; Gets the current zoom factor for the Parallax video card associated with the specified window.

Usage

int *XPlxGetZoomFactor(display, window)

Display *display;
Window window;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay();
window Specifies the window to get the data from.

Returns

The current zoom factor of the Parallax video card associated with the specified window.

Description

XPlxGetZoomFactor() queries the Parallax Graphics card associated with the specified window for its current zoom factor. The window can be associated with the Parallax Graphics video card by performing some video operation using the window as a parameter, or by a call to XPlxSetDrawabletoAdaptor().

Note: The zoom feature is available only for Parallax Graphics video overlay cards, but using XPlxGetZoomFactor will not cause problems for cross-platform development between video framebuffer and video overlay cards as long as both are using Sun Solaris 2.5 or version 9.3 for H-P or higher.

XPlxPutImage()

Parallax software for Sun Solaris 2.5 and version 9.3 for HP or higher; Draws an XImage into the Parallax video memory

Usage

void XPlxPutImage(display, window, gc, image, src_x, src_y, dest_x, dest_y, width, height)

Display *display;
Window window;
GC gc;
XImage *image;
int src_x;
int src_y;
int dest_x;
int dest_y;
unsigned int width;
unsigned int height;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay();
window Specifies the window to get the data from.
gc Specifies the graphics context
image Specifies the image you want to display
src_x,src_y Specify the x and y coordinates of the upper-left corner of the rectangle to be copied, relative to the origin of the image.
dest_x,dest_y Specify the x and y coordinates, relative to the origin of the window, where the upper-left corner of the copied rectangle will be placed.
width, height Specify the width and height in pixels of the rectangular area to be copied.

Description

XPlxPutImage() draws an XImage into the Parallax video memory. On Parallax framebuffer cards (XVideo, XVideo-VIO, PowerVideo, MultiVideo Sun cards), the XImage must have a depth of 24 bits. On all video overlay cards (XVideo Xtra and HP cards), the XImage must have a depth of 32 bits.

XPlxQueryConfig()

Determines which type of Parallax video board is currently installed, and builds an appropriate plx_IO structure (to manage drawables associated with input and output channels on the board).

Usage

plx_IO *XPlxQueryConfig (dpy, d, gc)

Display *dpy;
Drawable d;
GC gc;

Arguments

*dpy Specifies a pointer to the Display structure;
d Specifies the Drawable, which must be a window;
gc Specifies the Graphics Context

Returns

A filled in plx_IO structure.

Description

XPlxQueryConfig() queries the Parallax video board to determine which type of Parallax hardware is in use, and sets up a plx_IO structure with defaults appropriate for the hardware currently in use. Note: The hardware type for XVideo, PowerVideo, and MultiVideo boards from Parallax is PLX_XVIDEO_24. Use this function once at window-initialization time to set up the window for Parallax video inputs/outputs (I/Os). This function should be exectured before any other XPlx function, since it initializes pointers to a series of Parallax video I/O structures and sets the plx_hardware variable to its valid defaults:

Example

TO BE ADDED AT A LATER DATE

XPlxQueryVideo()

Queries the currently selected input channel to determine if a valid signal sync is found; if a valid sync is found, returns TRUE for the plx_signal variable, sync_ok, along with the characteristics of the incoming signal (as defined in the plx_signal structure); otherwise, returns a NULL

Usage

plx_signal *XPlxQueryVideo (dpy, d, gc)

Display *dpy;
Drawable d;
GC gc;

Arguments

*dpy Specifies a pointer to the Display structure;
d Specifies the Drawable, which must be a window;
gc Specifies the Graphics Context

Returns

A filled in plx_signal structure.

Description

XPlxQueryVideo() queries the hardware to determine if a valid signal sync is found on the connected input channel. If a valid signal sync is not found, video will not display. If a valid sync is found, this function returns TRUE for the plx_signal typedef, sync_ok, along with the characteristics of the incoming signal (as defined in the plx_signal structure in the XPlxExt.h file).

Overlay cards: If you are using zoom 2x mode, the width and height fields of the plx_signal structure will be twice the size of the selected video standard. For example, the NTSC standard is 640x480, but in zoom 2x, you will enter double that size: 1280x960.

Note: This function should be called after each use of XPlxVideoInputSelect().

Use this function to check for sync on the user-selected input channel (an indicator that the device is properly connected and that live video is being successfully received on that channel) and to return the actual characteristics of the incoming video signal.

If sync is not found, video will not be displayed. If the video characteristics do not match the parameters specified in the XPlxVideoInputSelect() call, video may not display properly.

Example

See the programming example for XPlxQueryConfig.

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxQueryConfig(), XPlxVideoInputSelect().

XPlxScaleCopyArea()

SunOS 4.1.x/Openwindows 3.06 or earlier releases only: Copies the contents of a window and displays this as scaled video in a second window.

Usage

void XPlxScaleCopyArea (dpy, sd, dd, gc, sx, sy, sw, sh, dx, dy, dw, dh)

Arguments

*dpy Specifies a pointer to the Display structure;
sd Specifies the source drawable, which must be a window;
dd Specifies the destination drawable, which must be a window;
gc Specifies the Graphics Context
sx,sy Specifies the origin of the source window
sw,sh Specifies the width and height of the source window
dx,dy Specifies the origin of the destination window
dw,dh Specifies the width and height of the destination window

Description

XPlxScaleCopyArea() copies the contents of a source window and scales it to fit into a destination window.

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxVideoScaleOutput()

XPlxSetVideoParameterString()

Video framebuffer cards only: Offers a limited set of special video modes provided by the Parallax video hardware.

Usage

void XPlxSetVideoParameterString (dpy, d, gc, string)

Display *dpy;
Drawable d;
GC gc;
char* string;

Arguments

*dpy Specifies a pointer to the Display structure;
d Specifies the Drawable, which must be a window;
gc Specifies the Graphics Context
string Specifies a pointer to a parameter string

Description

XPlxSetVideoParameterString() offers a limited set of special video modes provided by the Parallax video framebuffer cards.

Note: Cross-platform developers: If you write a cross-platform application for both Parallax framebuffer and overlay cards, using XPlxSetVideoParameterString() will not cause a problem. It will work for framebuffers and not work for overlays. Applications will compile and line with calls to XPlxSetVideoParameterString(), and the cross- platform support is provided. That is, you can take an application that uses this function on HP (like VideoTool), display that application on a framebuffer platform (Solaris 2.5), and the user will be able to use the special effects.

The programmer can use unique strings with this function to call a lower-level library of routines and change the behavior of video on the input or output channel.

Currently, the unique strings available to the programmer are as follows:

String Use

INVERTED To display reverse video (which looks like a film negative).
Example: XPlxSetVideoParameterString(dpy, d, gc, "input_config INVERTED");

NONINVERTED To restore normal video (turn off INVERTED effect).
Example: XPlxSetVideoParameterString(dpy, d, gc, "input_config NONINVERTED");

BW To display incoming full-color video in black-and-white
Example: XPlxSetVideoParameterString(dpy, d, gc, "input_config BW");

COLOR To restore the incoming video signal to full color
Example: XPlxSetVideoParameterString(dpy, d, gc, "input_config BW");

GENLOCK To lock signal sync of an incoming video signal on the current input channel to the signal sync of a video output signal on the current output channel
Example: XPlxSetVideoParameterString(dpy, d, gc, "output_config GENLOCK");

FREERUN To turn off the genlock effect
Example: XPlxSetVideoParameterString(dpy, d, gc, "output_config FREERUN");

Errors

BadDrawable
BadGC
BadMatch

Related Functions

None

XPlxSetZoomFactor()

Parallax software for Sun Solaris 2.5 and version 9.1 for HP or higher: Sets the zoom factor for the hardware attached to the specified window

Usage

Bool XPlxSetZoomFactor (display, window, zoomFactor)

Display *display;
Window window;
int zoomFactor;

Arguments

display Specifies a connection to the X server; returned from XOpenDisplay().
window Specifies the ID of the window associated with the Parallax Graphics card that you are interested in
zoomFactor Specifies the requested zoomFactor (either 1 or 2)

Returns

True If the call was successful
False If the call was unsuccessful

Description

XPlxSetZoomFactor() sets the zoom factor for the Parallax Graphics video card attached to the specified window. This call can return unsuccessfully if the Parallax Graphics hardware does not support zoom.

XPlxVideoInputSelect()

Sets digitization and display parameters for the video input signal.

Usage

void XPlxVideoInputSelect (dpy, d, gc, channel, standard, format, type)

Display *dpy;
Drawable d;
GC gc;
int channel, standard, format, type;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable, which must be a window

gc Specifies the Graphics Context.

channel Specifies which Parallax video input channel will carry the incoming video. (The programmer can associate one of two video channels with the window: PLX_INPUT_0, which is input #1 on the XVideo, Powervideo, and Multivideo boards; or PLX_INPUT_1, which is input #2, an input that's only available on the XVideo cards.) The upper 16 bits of the channel indicate the hardware instance. Example: to use the first channel on the second Parallax video board, use ((1<<16) | PLX_INPUT_0) as the channel.

standard Specifies which video signal standard the Parallax video hardware should "plan" to process when digitizing the incoming video signal. (The programmer can associate one of two video standards with the window: PLX_NTSC, which is NTSC, a standard used widely in the U.S.; or PLX_PAL, which is PAL, a standard used widely in Europe). (Note: PLX_SECAM is not currently implemented).

format Specifies which video signal format the Parallax video hardware should "plan" to process when digitizing the incoming video signal. (The programmer can associate one of four formats with the window: PLX_COMP, which is composite video; PLX_YC, which is SuperVHS video; PLX_RGB, which is RGB-compliant video; or PLX_YUV, which is YUV-component video.) The upper 16 bits of the format indicate the wire instance. Example: to select the "Video In Composite 2" wire, use ((1<<16) | PLX_COMP) as the format.

type Specifies which video-color type the Parallax video hardware should "plan" to process when color-decoding the incoming video signal for display. (The programmer can associate one color type with the window: PLX_RGB24, which is 24-bit RGB color, the only type currently supported by XVideo, PowerVideo, and MultiVideo.)

Description

XPlxVideoInputSelect() suggests a list of parameters to be used by the Parallax video hardware when it digitizes, color-decodes, and displays the video input signal.

To ensure good results, the programmer must set the input parameters to valid values for the hardare in use. Reasonable values for current Parallax video boards are provided below:

XVideo
channel PLX_INPUT_0 or PLX_INPUT_1
standard PLX_NTSC, or PLX_PAL; PLX_SECAM is not currently implemented through Xlib calls. A special environment variable must be set to enable SECAM decoding
format PLX_COMP (standard composite) or PLX_YC (SuperVHS)
type PLX_RGB24 (always: this is the only input type supported)

PowerVideo and MultiVideo
channel PLX_INPUT_0
standard PLX_NTSC, or PLX_PAL; PLX_SECAM is not currently implemented through Xlib calls. A special environment variable must be set to enable SECAM decoding
format PLX_COMP (standard composite) or (For newer HP only) PLX_YC (SuperVHS)
type PLX_RGB24 (always: this is the only input type supported)

XVideo-RGB
channel PLX_INPUT_0 or PLX_INPUT_1
standard PLX_NTSC, or PLX_PAL; PLX_SECAM is not currently implemented through Xlib calls. A special environment variable must be set to enable SECAM decoding
format PLX_RGB (RGB component) or PLX_YUV (YUV component)
type PLX_RGB24 (always: this is the only input type supported)

Example

XPlxVideoInputSelect(disp, win, gc, PLX_INPUT_0, PLX_NTSC, PLX_COMP, PLX_RGB24);

If the programmer hard codes values that are not valid for the type of Parallax video hardware and/or input signal currently in use, the incoming video signal may not be processed (digitized, color-coded, and/or displayed) correctly.

Multiple Cards : To select video input from the wire labeled "Video In Composite 2" to digitize an NTSC signal from the first digitizer of the Parallax video card in the second slot (first card is in the lowest slot number):

int hwInst = 1; /* 2nd video card */
int wireInst = 1; /* wire labelled "Video In Composite 2" */
int channel = PLX_INPUT_0;
int standard = PLX_NTSC;
int format = PLX_COMP;

XPlxVideoInputSelect(disp, win, gc, (hwInst<<16)|channel, standard, (wireInst<<16)|format, PLX_RGB24);

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxQueryConfig(), XPlxVideoOutputSelect().

XPlxVideoLive()

Displays unscaled live video in a window.

Usage

void XPlxVideoLive (dpy, d, gc, vx, vy, x, y, w, h) Display *dpy; Drawable d; GC gc; int vx, xy; int x, y, w, h;

Arguments

*dpy Specifies a pointer to the Display structure
d Specifies the Drawable, which must be a window
gc Specifies the Graphics Context
vx, vy Specifies the origin of the video input signal
x, y Specifies the origin of the window, which is where video digitization to the display begins.
w, h Specifies the width and height (the size) of the window.

Description

XPlxVideoLive() displays unscaled live video in a window. Video is digitized and displayed as 24-bit RGB.

Any live video window associated with the framebuffer I/O port is interrupted for the time necessary to digitize the image: This function directs the digitizer to stop digitization of the current live window before starting up digitization of the next window.

One live video window can be displayed by the PowerVideo and MultiVideo boards.

Two live video windows can be simultaneously displayed with the XVideo hardware (for inputs #1 and #2).

When more than two windows are displayed on dual-channel controllers, or when more than one window is displayed on single-channel controllers, the last window associated with the input channel will be live. The previous window associated with that same input channel will be stopped (a still is displayed continuously onscreen, and can be overwritted [damaged] with other display events).

General parameter restrictions, which are strictly enforced by the software, include:

0<=vx<=signal.w - w
0<=vy<=signal.h + signal.b - h
0< w <=signal.w - vx
0< h <=signal.h - vy

The display process is the same as for XPlxVideoStill: The origin of the video input signal (vx,vy) is mapped to the origin of the video display window (x, y), and video is digitized and displayed--at a 1:1 ration--in the window.

If the incoming video signal is larger than the window (w, h), the incoming signal will be cropped against the window.

To avoid displaying "black video" or portions of the blanking interval in a window, the size fo the window (w, h) should be smaller than or equal to the size of the video input signal (vw, vh).

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxVideoStop(), XPlxQueryConfig(), XPlxVideoInputSelect(), XPlxQueryVideo().

XPlxVideoOutputSelect()

Sets digitization and display parameters for the video output signal.

Usage

void XPlxVideoOutputSelect (dpy, d, gc, channel, standard, format, type)

Display *dpy;
Drawable d;
GC gc;
int channel, standard, format, type;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable, which must be a window

gc Specifies the Graphics Context.

channel Specifies which Parallax video output channel will carry the exported video. (The programmer can associate the video output channel with the output region: PLX_INPUT_0, which is output #1, only available on the XVideo cards.) Or, to disable output from the output region, the programmer can specify PLX_IO_OFF). The upper 16 bits of the channel indicate the hardware instance. Example: to use the first channel on the second Parallax video board, use ((1<<16) | PLX_OUTPUT_0) as the channel.

standard Specifies which video signal standard the Parallax video hardware should "plan" to process when digitizing the outgoing video signal. (The programmer can associate one of two video standards with the window: PLX_NTSC, which is NTSC, a standard used widely in the U.S.; or PLX_PAL, which is PAL, a standard used widely in Europe). (Note: PLX_SECAM is not currently implemented).

format Specifies which video signal format the Parallax video hardware should "plan" to process when digitizing the incoming video signal. (The programmer can associate one of four formats with the window: PLX_COMP, which is composite video; PLX_YC, which is SuperVHS video; PLX_RGB, which is RGB-compliant video; or PLX_YUV, which is YUV-component video.) The upper 16 bits of the format indicate the wire instance, but is not meaningful with the current generation of product.

type Specifies which video-color type the Parallax video hardware should "plan" to process when color-decoding the incoming video signal for display. (The programmer can associate one color type with the window: PLX_RGB24, which is 24-bit RGB color, the only type currently supported by XVideo, PowerVideo, and MultiVideo.)

Description

The function is only supported on Parallax XVideo boards.

XPlxVideoOutputSelect() passes digitization parameters for the video output signal to the server; the digitizer will use these parameters to digitize and output video.

The XPlxVideoOutputSelect function specifies values to be used to create a video output signal from an output region on the display.

To ensure good results, set the output parameters to valid values for the hardware in use. Reasonable values for current Parallax video boards are provided below:

XVideo
channel PLX_OUTPUT_0
standard PLX_NTSC, or PLX_PAL; PLX_SECAM is not supported
format PLX_COMP (standard composite) or PLX_YC (SuperVHS)
type PLX_RGB24 (always: this is the only input type supported)

XVideo-RGB
channel PLX_OUTPUT_0
standard PLX_NTSC, or PLX_PAL; PLX_SECAM is not supported
format PLX_RGB (RGB component) or PLX_YUV (YUV component)
type PLX_RGB24 (always: this is the only input type supported)

Example

To "hard-code" output values in the parameters list, do the following:

XPlxVideoOutputSelect(disp, win, gc, PLX_OUTPUT_0, PLX_NTSC, PLX_COMP, PLX_RGB24);

Multiple Cards : To select video input from the wire labeled "Composite Output" to create an NTSC signal from the Parallax video card in the second slot (first card is in the lowest slot number):

int hwInst = 1; /* 2nd video card */
int wireInst = 1; /* wire labelled "Composite Output" */
int channel = PLX_OUTPUT_0;
int standard = PLX_NTSC;
int format = PLX_COMP;

XPlxVideoOutputSelect(disp, win, gc, (hwInst<<16)|channel, standard, (wireInst<<16)|format, PLX_RGB24);

Note: By default, the output channel is disabled (set to PLX_IO_OFF). When output is enabled, the output channel is set to PLX_OUTPUT_0.

Note: If hard-coded values are not valid for the type of hardware and signal in use, the video signal may fail to be digitized and exported correctly.

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxQueryConfig(), XPlxVideoInputSelect(), XPlxQueryVideo().

XPlxVideoScaleOutput()

Outputs the contents of a specified region of the display as scaled video.

Usage

void XPlxVideoScaleOutput (dpy, d, gc, x, y, w, h, vx, vy, vw, vh)

Display *dpy;
Drawable d;
GC gc;
int x, y, w, h; int vx, vy, vw, vh;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable, which must be a window

gc Specifies the Graphics Context.

x,y Specifies the postion within the drawable to start the output from.

w, h Specifies the width and height (the size) of the region within the drawable to output. In zoom 2x mode, w and h should indicate the actual window size.

vx, vy Specifies the starting position within the output signal where the information from the drawable should be displayed.

vw, vh Specifies the width and height (the size) of the viewable portion of the video signal (signal.w, signal.h). In zoom 2x mode, vw and vh should indicate the actual window size.

Description

XPlxVideoScaleOutput() outputs the contents of a specified region on the display as scaled video.

General parameters, which are strictly enforced by the software, include:
0 <= w <= vw
0 <= h <= vh
(This allows for scaling up but not scaling down of the image).

The scaled output is produced as follows: The origin of the video output region on the display (x, y) is mapped to the origin of the viewable portion of the output signal (vx, vy), and Video is digitized and output to the connected outpu device in a signal format (including blanking interval) that is appropriate for the signal standard in use on the current output channel.

Note: If PLX_IO_OFF is specified by XPlxVideoOutputSelect, the video output produces a blank signal

The viewable portion of the output signal specified by (vw, vh) can be larger than or equal to the video output region specified by (w, h). (If the output region size is less than the signal size, the image will be scaled up.)

The programmer may also make use of the (vx, vy) parameters to "border" the output, that is, take a region smaller than the output signal, and surround it on the signal with a black border. An example would be:

XPlxVideoScaleOutput(display, window, outputGC,
			0, 0,
			windowwidth, windowheight,
			(signalwidth-windowwidth)/2,	/* Center */
			(signalheight-windowheight)/2,  /* Center */
			signalwidth, signalheight);

Output pixels cannot come from--or be mapped to--"offscreen" locations. On video overlay cards (Xvideo Xtra and HP), the output rectangle must be either a JPEG or video window. Selecting areas outside of JPEG or Video windows (to display) results in unpredictable colors. In general, this function will do the best it can to position an output rectangle onscreen and to deliver the output that you asked for.

Any live video window associated with the framebuffer I/O port is interrupted for the time necessary to output the image.

Video overlay cards, zoom 2x: If you are using zoom 2x, the width and height passed into this function should take into account the zoom factor. If you are in zoom 2x and wish to turn on NTSC output, use a call similar to this:

XPlxVideoScaleOutput(display, window, gc, 0, 0,
			640 * zoomFactor, 480 * zoomFactor, 0, 0,
			640 * zoomFactor, 480 * zoomFactor);

Note: As multiple video operations are bing performed on the same window, it is mandatory that the Output function be the first function called (before the Live Video or JPEG functions).

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxQueryConfig(), XPlxVideoInputSelect(), XPlxVideoOutputSelect(), XPlxQueryVideo().

XPlxVideoSqueezeLive()

Displays scaled live video in a window

Usage

void XPlxVideoSqueezeLive (dpy, d, gc, vx, vy, vw, vh, x, y, w, h)

Display *dpy;
Drawable d;
GC gc;
int vx, vy, vw, vh; int x, y, w, h;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable, which must be a window

gc Specifies the Graphics Context.

vx, vy Specifies the origin of the video input signal

vw, vh Specifies the width and height (the size) of the video input signal.

x,y Specifies the origin of the Parallax video input window, which is where digitization to the display begins.

w, h Specifies the width and height (the size) of the Parallax video input window.

Description

XPlxVideoSqueezeLive() displays scaled live video in a window. The video image is scaled to the specified size.

General parameters, which are strictly enforced by the software, include:
0 <= vx <= plx_signal.w
0 <= vy <= plx_signal.h
0 <= vw <= plx_signal.w - vx
0 <= vh <= plx_signal.h - vy
-vw <= w <= vw
-vh <= h <= vh

If vy < signal.b, then lines from the vertical blanking interval (signal.b) will display.

Additional parameter restrictions are:
1/4096 <= w/vw <=1

The digitization and display process is as follows: The origin of the video input signal (vx, vy) is mapped to the origin of the video display window (x,y), and video is digitized and displayed as scaled live video in a window.

The size of the video display window (w,h) can be less than, greater than, or equal to the size of the video input signal (vw, vy). Scaled down video is achieved through pixel sampling (also called "pixel dropping"). Scaled up video is achieved through pixel replication.

Video is digitized and displayed as 24-bit RGB images.

Any live video window associated with the framebuffer I/O port is interrupted for the time necessary to digitize the image: This function directs the digitizer to stop digitization of the current live window before starting up digitization of the next window.

One live video window can be displayed by the PowerVideo and MultiVideo boards.

Two live video windows can be displayed simultaneously with the XVideo hardware (for inputs #1 and #2).

When more than two windows are displayed on dual-channel controllers, or when more than one window is displayed on single-channel controllers, the last window associated with the input channel will be live. The previous window associated with that same input channel will be stopped (a still is displayed continuously onscreen, and can be overwritten [damaged] with other display events).

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxVideoStill(), XPlxQueryConfig(), XPlxVideoInputSelect(), XPlxQueryVideo().

XPlxVideoSqueezeStill()

Displays a scaled still frame of video in a window

Usage

void XPlxVideoSqueezeStill (dpy, d, gc, vx, vy, vw, vh, x, y, w, h)

Display *dpy;
Drawable d;
GC gc;
int vx, vy, vw, vh; int x, y, w, h;

Arguments

Description

XPlxVideoSqueezeStill() displays a scaled still frame of video in a window. The video image is scaled to the specified size.

General parameters, which are strictly enforced by the software, include:
0 <= vx <= plx_signal.w - vw
0 <= vy <= plx_signal.h + plx_signal.b - vh
0 <= vw <= plx_signal.w - vx
0 <= vh <= plx_signal.h + plx_signal.b - vy
0 <= w <= plx_signal.w - vx
0 <= h <= plx_signal.h + plx_signal.b - vy

Additional parameter restrictions are:
1/4096 <= w/vw <=1

The digitization and display process is as follows: The origin of the video input signal (vx, vy) is mapped to the origin of the video display window (x,y), and video is digitized and displayed as scaled still video in a window.

The size of the video display window (w,h) can be less than, greater than, or equal to the size of the video input signal (vw, vy). Scaled down video is achieved through pixel sampling (also called "pixel dropping"). Scaled up video is achieved through pixel replication.

Note: This call is slow in order to get both fields in your video frame, and avoid image tearing. If it is more important to you to stop immediately rather than have an un-torn image, use XPlxVideoStop() instead.

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxVideoStop(), XPlxVideoSqueezeLive(), XPlxQueryConfig(), XPlxVideoInputSelect(), XPlxQueryVideo().

XPlxVideoStill()

Displays an unscaled still frame of video in a window

Usage

void XPlxVideoStill (dpy, d, gc, vx, vy, x, y, w, h)

Display *dpy;
Drawable d;
GC gc;
int vx, vy; int x, y, w, h;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable, which must be a window

gc Specifies the Graphics Context.

vx, vy Specifies the origin of the video input signal

x,y Specifies the origin of the Parallax video input window, which is where digitization to the display begins.

w, h Specifies the width and height (the size) of the Parallax video input window.

Description

XPlxVideoStill() displays still video in a window. The video image is cropped to the specified size.

General parameters, which are strictly enforced by the software, include:
0 <= vx <= plx_signal.w - w
0 <= vy <= plx_signal.h + plx_signal.b - h
0 <= w <= plx_signal.w - vx
0 <= h <= plx_signal.h - vy

The digitization and display process is the same as for XPlxVideoLive: The origin of the video input signal (vx, vy) is mapped to the origin of the video display window (x, y), and video is digitized and displayed--at a 1:1 ratio--in the window.

If the size of the incoming video signal (vw, vh) is larger than the size of the video display window (w, h), the incoming signal will be cropped against the display window.

Note: To avoid displaying "black video" or portions of the blanking interval in a window, the size of the display window (w, h) should be smaller than or equal to the size fo the video input signal (vw, vh).

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxVideoLive(), XPlxQueryConfig(), XPlxVideoInputSelect(), XPlxQueryVideo().

XPlxVideoStop()

Stops live video in a window

Usage

void XPlxVideoStop (dpy, d, gc)

Display *dpy;
Drawable d;
GC gc;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable, which must be a window

gc Specifies the Graphics Context.

Description

XPlxVideoStop() stops digitization and display of live video in a window.

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxVideoLive(), XPlxVideoSqueezeLive().

XPlxVideoTag()

Video framebuffers only: Sets up the graphics context to tag pixels for a spcified drawing operation.

Note: Since XVideo Xtra and HP cards are overlay cards instead of framebuffer cards, the actual GC in use for the video window under the graphics server executing on the Sun or HP graphics controller is irrelevant. You do not have to set special tags.

Usage

void XPlxVideoTag(dpy, d, gc, type)

Display *dpy;
Drawable d;
GC gc;
int type;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable, which must be a window

gc Specifies the Graphics Context.

type Specifies the type of drawing operation to be performed. The programmer can set up the graphics context for one of several types of drawing operations: PLX_GRAPHICS, PLX_VIDEO, or PLX_VIDEO_OVR.

Description

XPlxVideoTag() will set up the graphics context of the window for one of the following types of drawing operations:

PLX_GRAPHICS (the default) When the GC is set up with this type, the drawing operation tags affected pixels to display 24-bit graphics

PLX_VIDEO When the gc is set up with this type, the drawing operation tags affected pixels to display 24-bit video

PLX_VIDEO_OVR When the gc is set up with this type, the drawing operation does nothing to pixels tagged to display video. Use this tag type to override the clear screen event on video window resizes or moves (so that the window displays video continuously and doesn't "flash back" before window redraws).

Until the XPlxVideoTag is set to one of these tag types, the tag is unknown, and XPlxVideoTag will assume a graphics context that is suitable for whatever operation you're trying to do (displaying either graphics or video).

Use this function after XPlxVideoInputSelect() and XPlxVideoQuery() functions and before any window-creation functions (like XPlxVideoLive) to set up the graphics context for drawing operations in the window.

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxVideoLive(), XPlxVideoSqueezeLive()

XPlxVideoValueLoad()

Video framebuffer (Sun) cards only: Applies user-specified color settings to the current window.

Usage

void XPlxVideoValueLoad(dpy, d, gc, sat, cont, hue, brit)

Display *dpy;
Drawable d;
GC gc;
int sat, cont, hue, brit;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable, which must be a window

gc Specifies the Graphics Context.

sat Specifies a saturation value. Valid values can be 0 through 255. (0 creates a black-and-white image)

cont Specifies a contrast value. Valid values can be 0 through 255.

hue Specifies a hue value. Valid values can be 0 through 255

brit Specifies a brightness value. Valid values can be 0 through 255.

Description

XPlxVideoValueLoad() applies user-specified color settings to the current window.

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxVideoValueQuery(), XPlxVideoValueRecall(), XPlxVideoValueSave().

XPlxVideoValueQuery()

Video framebuffer (Sun) cards only: Returns the values of a window's current color settings (brightness, contrast, hue, saturation).

Usage

void XPlxVideoValueQuery(dpy, d, gc, sat, cont, hue, brit)

Display *dpy;
Drawable d;
GC gc;
int *sat, *cont, *hue, *brit;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable, which must be a window

gc Specifies the Graphics Context.

*sat Specifies a pointer to the address containing the video saturation value. (0 through 255)

*cont Specifies a pointer to the address containing the contrast value. (0 through 255)

*hue Specifies a pointer to the address containing the hue value. (0 through 255)

*brit Specifies a pointer to the address containing the brightness value. (0 through 255)

Description

XPlxVideoValueQuery() returns the values of a window's current color settings (brightness, contrast, hue, saturation).

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxVideoValueLoad(), XPlxVideoValueRecall(), XPlxVideoValueSave().

XPlxVideoValueRecall()

Video framebuffer (Sun) cards only: Sets the window's color settings (brightness, contrast, hue, saturation) to those stored in one of the on-board NVRAM locations.

Usage

void XPlxVideoValueRecall(dpy, d, gc, nvselect)

Display *dpy;
Drawable d;
GC gc;
int nvselect;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable, which must be a window

gc Specifies the Graphics Context.

nvselect Specifies the NVRAM that contains color settings for a video window. (The programmer can recall values from either of three NVRAM addresses: FACTORY, which contains factory-set and unchangeable color settings, or USER0 or USER1, which contain user-specified settings.)

Description

XPlxVideoValueRecall() sets the window's color settings (brightness, contrast, hue, saturation) to those stored in one of the on-board NVRAM locations. (Color settings can be stored in the NVRAM using XPlxVideoValueSave).

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxVideoValueLoad(), XPlxVideoValueQuery(), XPlxVideoValueSave().

XPlxVideoValueSave()

Video framebuffer (Sun) cards only: Saves the current video (brightness, contrast, hue, saturation) values as user preferences in a specified NVRAM location.

Usage

void XPlxVideoValueSave(dpy, d, gc, nvselect)

Display *dpy;
Drawable d;
GC gc;
int nvselect;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable, which must be a window

gc Specifies the Graphics Context.

nvselect Specifies the non-volatile RAM NVRAM location. (The programmer can store values in either of two NVRAM addresses: USER0 or USER1).

Description

XPlxVideoValueSave() saves the current color settings (brightness, contrast, hue, saturation) to one of the on-board NVRAM locations. These settings can later be retrieved with XPlxVideoValueRecall().

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxVideoValueLoad(), XPlxVideoValueQuery(), XPlxVideoValueRecall().

JPEG Functions

The following pages describe the JPEG functions that are defined in out Xlib extension library, libXPlx.a.

These functions support the compression and decompression of Parallax video images and 24-bit graphics and can be used for video display, for video storage to disk, for direct-memory access of video over the network, or for vidoe captures to Parallax-proprietary JPEG movie files.

Note: These functions will return errors on the MultiVideo and XVideo (non-compression) boards for the Sun platform, which are not equipmed with the Parallax video JPEG hardware. They execute as no-ops on the H-P MultiVideo700 boards.

Note: To use the Parallax JPEG software, you should be familiar with the JPEG and ISO compression/decompression standards defined in Annex K of the International Organization for Standardization (ISO) Committee Draft (CD) Digital Compression and Coding of Continuous-tone Still Images.

Function	Summary
MakeQTable()	Creates a JPEG-standard quantization table and scales the table using the specified quantization (Q) factor.
XPlxCreateCImage()	Allocates memory for an XPlxCImage structure
XPlxDestroyCImage()	Deallocates memory associated with a compressed image
XPlxGetCImage()	Compresses the contents of a window (or portion of a window)
XPlxPutCImage()	Displays a compressed images, which is squeezed or cropped to fit in the destination window.
XPlxPutTable()	Stores the JPEG-standard quantization and/or Huffman coding/decoding table/s in the associated graphics context.
XPlxShmCreateCImage()	Creates an XPlxCImage structure for image data using M.I.T. shared memory functions
XPlxShmGetCImage()	Grabs a compressed image from a window and places it in the shared memory buffer, then returns a pass/fail status.
XPlxShmPutCImage()	Takes an image from the shared memory buffer and decompresses it, then returns a pass/fail status.

Using Shared-Memory for JPEG Compression

Two types of JPEG image-storage functions are provided (or are available*) for your use:

Table 2-4

Standard Memory Functions	Shared Memory Functions
XPlxCreateCImage()	XPlxShmCreateCImage()
XPlxGetCImage()	XPlxShmGetCImage()
XPlxPutCImage()	XPlxShmPutCImage()
XPlxDestroyCImage()	XPlxShmDetach() (a)

(a) M.I.T.'s XShmDetach() function works well with the XPlx functions.

Standard functions may be used in any application, and are required in any network applications. These functions are modeled after the standard XCreateImage(0, XGetImage(), XPutImage(), and XDestroyImage() functions. Shared memory functions are provided to optimize client/server performance when both are running on the same machine and will not work in networked client/server applications. The fucntions use shared memory as an interim storage location for compressed data, which prevents unnecessary copying of compressed image data. These shared memory functions are modeled after M.I.T.'s XShmCreateImage(), XShmGetImage(), and XShmPutImage().

Note: Debug you code using standard compression calls before attempting to use the shared memory calls. Include the following information in your kernel to use the shared memory functions on the Sun platform: options IPCSHMEM

Note: On the H-P platform, your HP-UX version must be 9.03 or greater, and you must use Parallax version 9.3 or higher to have shared memory support.

Note: If you are writing your own application supporting H-P with shared memory (Parallax software version 9.3 or higher for H-P), and if there is a possibility that you may use software decompression of JPEG data, then you should search for and remove a string of marker code (FFFFFFD0) in each JPEG frame before you write the frame. In Parallax software version 9.3 or higher for H-P, MovieTool and VideoTool remove this data; scomp does not. for more information, please see XPlxShmGetCImage(), and Xt. We provide an example of how to search for and delete the data.

Deallocating Shared Memory

Memory-sharing programs based on Parallax/M.I.T.'s shared memory functions should be designed to deallocate shared memory upon their completion.

However, if you ever need to manually deallocate shared memory, you can do so using the following steps:

1. Determine the addresses of shared memory blocks currently allocated on your system. To do this, type the following at the host command line:

host: ipcs -m

An IPC status table with information similar to the following will then appear on your screen:

 IPC status from system as of Fri Dec 20 08:54:49 1993

	T ID  KEY MODE OWNER GROUP
	Shared Memory:
	m 1600 0x00000000 --rw-rw-rw- user sw
	m 201 0x00000000 --rw-rw-rw- user sw
	m 102 0x00000000 --rw-rw-rw- user sw
	m 3 0x00000000 --rw-rw-rw- user sw
	m 4 0x00000000 --rw-rw-rw- user sw

2. Deallocate each block of shared memory. To do this, type the following at the host command line:

host: ipcrm -m address1 -m address2 -m address3 -m address4

For example, to deallocate all of the block of shared memory shown in the sample IPC status table above, you'd type:

host: ipcrm -m 1600 -m 201 -m 102 -m 3 -m 4

3. Make sure that every block of shared memory has been successfully deallocated. To do this, type the following at the host command line:

host: ipcs -m

An IPC status table with NULL information should then appear on your screen:

    IPC status from system as of Fri Dec 20 08:54:49 1993

	T ID  KEY MODE OWNER GROUP
	Shared Memory:

If shared memory blocks are still present, repeat step 2 above to deallocate the remaining blocks of shared memory.

MakeQTables()

Creates a JPEG-standard quantization table and scales the table using the specified quantization factor.

Usage

Int MakeQTables(factor, pqtable);

int factor;
unsigned char **pqtable;

Arguments

factor Specifies a quantization factor, we recommend that you specify a number between 25 and 1000, and have found that Qfactors between 50 and 100 return good results.
pqtable Specifies a pointer to a point to a char buffer

Description

MakeQTables() returns the length (in bytes) of the qtable it has created and sets up a pointer to space that's allocated by malloc() and that's filled in with the new Qtable.
Note: The quantization factor that you specify will be used to adjust the image compression ratio, which effects an adjustment of the image quality: To improve the image quality (but at the expense of increasing image size), specify a low-value factor to set up a lower compression ration; to improve the compression ratio (at the expense of reducing the image quality), specify a high-value factor to set up a higher compression ratio. (Actual compression ratios [algorithm yields] will depend upon the content of the image being compressed.)

Note: The Q tables were different for Solaris 2.4, H-P version 9.2, and earlier Sun releases. We found out that our Q tables were not standard, so we corrected them for our Solaris 2.5 (framebuffer and overlay) and H-P versions 9.3 or higher software releases. (For more information, see fixMovieQ in Appendix C of your Sun or H-P Multimedia Users Guide.

Related Functions

XPlxCreateCimage(), XPlxDestroyCImage(), XPlxGetCImage(), XPlxPutCImage(), XPlxPutTable().

XPlxCreateCImage()

Allocates memory for an XPlxCImage structure.

Usage

XPlxCImage *XPlxCreateCImage(dpy, data, size, width, height);

Display *dpy; char *data; int size; unsigned int width; unsigned in height;

Arguments

*dpy Specifies a pointer to the Display structure

*data Specifies a pointer to JPEG-compressed data

size Specifies the size of the compressed data in bytes.

width Specifies the width of the compressed image.

height Specifies the height of the compressed image.

Description

XPlxCreateCImage() allocates the memory needed for an XPlxCImage structure and fills in the data, size, and width parameters of this structure:

typedef struct _XPlxCImage {
	int width, height;			/* size of image		*/
	int size;				/* size in bytes of image	*/
	char *data;				/* pointer to image data	*/
	XShmSegmentInfo *info;			/* shared memory segment info	*/
} XPlxCImage;

Errors

A NULL is returned if XPlxCreateCimage() was unable to allocate storage for the XPlxCIamge structure.

Related Functions

XCreateImage(), XPlxDestroyCImage(), XPlxGetCImage(), XPlxPutCImage().

XPlxDestroyCImage()

Deallocates memory associated with a compressed image.

Usage

int XPlxDestroyCImage(ximage)

XPlxCImage *ximage;

Arguments

*ximage Specifies a pointer to the XPlxCImage structure

Description

XPlxDestroyCImage() deallocates the memory holding the XPlxCImage structure and the memory holding the actual image data, provided that the data member of that structure is not NULL. The memory is allocated and is associated with a compressed image by an XPlxCreateCImage() call or by XPlxGetCImage() call.

Note: If shared memory is used to create the Parallax XView-based VIDEO_IN object, the allocation and deallocation of memory is handled automatically. If normal memory is used, however, XPlxDestroyCImage() should be used to deallocate the memory once the client is done with it. This not applies to the Sun framebuffers only.

Related Functions

XPlxCreateCImage(), XDestroyImage(), XPlxGetCImage(), XPlxPutCImage().

XPlxGetCImage()

Compresses the contents of a window (or portion of a window).

Usage

XPlxCImage *XPlxGetCImage(dpy, d, gc, src_x, src_y, src_w, src_h, dst_w, dst_h);

Display *dpy; Drawable d; GC gc; int src_x, src_y; unsigned int src_w, src_h; unsigned int dst_w, dst_h;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable (which must be a window) to get the compressed image data from

gc Specifies the Graphics Context

src_x, src_y Specifies the origin of the source window, which contains the image to be compressed (relative to the origin of the drawable).

src_w, src_h Specifies the width and height of the source window. The area of this window must be a multiple of 8 (8xzoomFactor), since JPEG compression processes pixels in sets of 8. In zoom 1x and zoom 2x, src_w and src_h should reflect the actual size of the window.

dst_w, dst_h Specifies the width and height of a destination window, which can be used to scale up a source window (for example, to scale a quarter-size source window to full size) before compressing it. In zoom 1x and zoom 2x, dst_w and dst_h should reflect the actual size of the window.

Description

XPlxGetCImage() returns a compressed image from a source rectangle using the table stored in the graphics context by the XPlxPutTable() function.

XPlxGetCImage creates an XPlxCImage() structure, which contains a pointer to compressed image data:

typedef struct _XPlxCImage {
	int width, height;			/* size of image		*/
	int size;				/* size in bytes of image	*/
	char *data;				/* pointer to image data	*/
	XShmSegmentInfo *info;			/* shared memory segment info	*/
} XPlxCImage;

/* Get a compressed image */
jpegImage = XPlxGetCImage(display, recordWin, recordGC, 0, 0,
			  width, height, width, height);
/* Display the image in another window.  NOTE:  The image size	*/
/* may not be the same as what you passed into XPlxGetCImage()  */
XPlxPutCImage(display, playWin, playGC, 0, 0, 
		jpegImage->width, jpegImage->height,
		0, 0, jpegImage->width, jpegImage->height, 0);

General parameter restrictions are: src_w, src_h <= dst_w, dst_h

Video overlay cards: The width and height passed in to this function should be divided by the zoom factor. For example, if you are using zoom 2x on a 1280x960 window, you should pass 640x480 into XPlxGetCImage() for the width and height.

This function allocates storage space to hold the JPEG image data. In zoom 2x mode, the width and height returnced from XPlxGetCImage() indiecate 2 times the actual size. If you are saving the data to a file, it is important to use the correct width and gheit in the image header. You must destroy this space using XPlxDestroyCImage once you have decompressed the image.

Note: If you are saving JFIF images, you may want to check that the image width is divisible by 16 before using XPlxPutCImage, and reduce the image size if needed. The reason is to make the image displayable by third party applications such as ImageMagick's "display" that require a JFIF image width that is divisible by 16. See MovieTool (H-P version 9.3 or higher) for an example of how to do this automatically.

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxCreateCImage(), XPlxDestroyCImage(), XPlxPutCImage().

XPlxPutCImage()

Displays a compressed image, which is squeezed or cropped to fit in the destination window.

Usage

XPlxPutCImage(dpy, d, gc, image, src_x, src_y, src_w, src_h, dst_x, dst_y, dst_w, dst_h, flag);

Display *dpy;
Drawable d;
GC gc;
XPlxCImage *image;
int src_x, src_y;
unsigned int src_w, src_h;
int dst_x, dst_y;
unsigned int dst_w, dst_h;
int flag;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable (which must be a window) to get the compressed image data from

gc Specifies the Graphics Context

image Specifies the compressed image to be displayed

src_x, src_y Specifies the starting point for decompression of the source image (or subset of the source image)

src_w, src_h Specifies the width and height of the source image (or subset of the source image). In zoom 1x and zoom 2x, src_w and src_h should reflect the actual size of the window. Example: src_w = windowWidth/zoomFactor.

dst_w, dst_h Specifies the width and height of a destination window, In zoom 1x and zoom 2x, dst_w and dst_h should reflect the actual size of the window.

flag Specifies whether the source image should be squeezed (set to 1) or cropped (set to 0) in the destination window.

Description

Based on quanitzation data in the QTable, which is loaded with XPlxPutTable() or autoloaded with the image data, XPlxPutCImage() decompresses a source image and displays this as squeeze or cropped to fit in a destination window.

Video overlay cards: The width and height passed in to this function should be divided by the zoom factor. For example, if you are using zoom 2x on a 1280x960 window, you should pass 640x480 into XPlxPutCImage() for the width and height.

Note: A QTable included as part of the image data will be used instead of a QTable stored in the graphics context. For more details about how a QTable is loaded, see XPlxPutTable().

The XPlxCImage structure defines how the image is rendered:

typedef struct _XPlxCImage {
	int width, height;			/* size of image		*/
	int size;				/* size in bytes of image	*/
	char *data;				/* pointer to image data	*/
	XShmSegmentInfo *info;			/* shared memory segment info	*/
} XPlxCImage;

Note: The compressed image size must not exceen 256K bytes of data. If it does, XPlxPutCImage will display no data, and will display this message until an image of the legal size is processed: XPlxPutCImage: too much data to transfer. avail=262096, size=nnnnn.

The normal settings for the decompression of the full-size image are:

src_x = src_y = dst_x = dst_y = 0
dst_w = src_w = XPlxCImage.width
dst_h = src_h = XPlxCImage.height

General parameter restrictions are: dst_w/zoomFactor, dst_h/zoomFactor <= src_w, src_h <= XPlxCimage.width, XPlxCImage.height

Note: If the compressed image data is corrupted (or doesn't follow the JPEG standard), you'll get unpredictable results.

Note: The src_x, src_y, src_w, and src_h parameters may be used to select a subset of the image to be decompressed, and the subsets may be scaled down or cropped by specifying a smaller destination rectangle and setting the flag accordingly.

Errors

BadDrawable
BadGC
BadMatch

Related Functions

XPlxCreateCImage(), XPlxDestroyCImage(), XPlxGetCImage().

XPlxPutTable()

Stores the JPEG-standard quantization and/or Huffman coding/decoding table(s) in the associated graphics context.

Usage

XPlxPutTable(dpy, d, gc, table, size, dir);

Display *dpy;
Drawable d;
GC gc;
char *table;
int size;
Bool dir;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable (which must be a window) to get the compressed image data from

gc Specifies the Graphics Context

*table Specifies a pointer to the JPEG-standard quantization table or Huffman table to be used.

size Specifies the size of the data in the acquired table

dir Specifies the direction for data compression/decompression (0 = compression, 1 = decompression)

Description

XPlxPutTable() stores a specified JPEG-standard quantization and/or Huffman coding/decoding table in the associated graphics context.

To compress or decompress an image, you MUST access quantization table data in one of two ways:

1. Load a QTable into the graphics context with this call.

2. For decompression only: Include QTable data in the image data to be decompressed. The QTable data included as part of the image data supercedes (will be used instead of) a QTable stored in the graphics context.

If you don't access a QTable in either of these two ways, your compression/ decompression functions will fail.

At your option, you CAN access Huffman coding/decoding table data in one of two ways:

1. Load a Huffman table into the graphics context with this call.
2. For decompression only: Include Huffman table data in the image data to be decompressed. The Huffman table data included as part of the image data supercedes (will be used instead of) a Huffman table stored in the graphics context.

If you do not access a Huffman table in either of these two ways, a default table-- one that is defined in Annex K of the ISO CD 10918, Digital compression and Coding of Continuous Tone Still Images--will be used to compress/decompress your image. If you're planning to use a customized JPEG-standard quantization or Huffman table with this call, be sure to follow all of the format constraints defined in Annex K.

Note: We support a subset of the "JPEG Baseline Algorithm". Specifically, we support only YUV 4:2:2 encoding in which the YUV is sampled 2:1 in the x direction, where Y (luminance) is component 1 and UV (chrominance) are components 2 and 3 (Y:U:V). Two-byte marker codes are included in a compressed bit stream to identify various parts of the bit stream. All marker codes that are included must precede the image data you plan to decompress. Parallax video software, however, processes the Define Quantization marker code (DQT), the Define Huffman Table marker code (DHT), the Start of Frame marker code (SOF), and the Start of Scan marker code (SOS), and ignores all others.

Errors

BadDrawable
BadGC
BadMatch

Related Functions

MakeQTables(), XPlxCreateCImage(), XPlxDestroyCImage(), XPlxGetCImage(), XPlxPutCImage().

XPlxShmCreateCImage()

Create an XPlxCImage structure for image data using M.I.T. shared memory functions.

Usage

XPlxCImage *XPlxShmCreateCImage(dpy, data, shminfo, size, width, height);

Display *dpy;
char *data;
XShmSegmentInfo *shminfo;
int size;
unsigned int width;
unsigned int height;

Arguments

*dpy Specifies a pointer to the Display structure

*data Specifies a pointer to JPEG-compressed data

*shminfo Specifies a pointer to the buffer-memory address
(a number of contiguous bytes of memory)
size Specifies the size of the compressed data in bytes.

width Specifies the width of the compressed image.

height Specifies the height of the compressed image.

Description

XPlxShmCreateCImage() allocates the memory needed for an XPlxCImage structure and fills in the data, size, and width parameters of this structure:

typedef struct _XPlxCImage {
	int width, height;			/* size of image		*/
	int size;				/* size in bytes of image	*/
	char *data;				/* pointer to image data	*/
	XShmSegmentInfo *info;			/* shared memory segment info	*/
} XPlxCImage;

Note: Image data referenced in the XPlxCImage structure is a shared memory buffer.

You can create this structure manually, if you like. If the server and client programs are local to each other (share the same system), you can use this call with the other XPlxShm* calls to eliminate the need to copy image data over the network for the client's use.

Note: To free up memory, use M.I.T.'s standard XShmDetach() function instead of the XPlxDestroyCImage() function.

Errors

BadDrawable
BadGC
BadMatch

Related Functions

MakeQTables(), XPlxCreateCImage(), XPlxDestroyCImage(), XPlxGetCImage(), XPlxPutCImage(), XPlxPutTable(), XShmDetach().

XPlxShmGetCImage()

Grabs a compressed image from a window and places it in the shared memory buffer, then returns a pass/fail status

Usage

Status *XPlxShmGetCImage(dpy, d, gc, image, src_x, src_y, src_w, src_h);

Display *dpy;
Drawable d;
GC gc;
XPlxCImage *image;
int src_x, src_y;
unsigned int src_w, src_h;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable (which must be a window) to get the compressed image data from

gc Specifies the Graphics Context

image Specifies a pointer to the XPlxCImage structure

src_x, src_y Specifies the origin of the source window, which contains the image to be compressed (relative to the origin of the drawable).

src_w, src_h Specifies the width and height of the source window. The area of this window must be a multiple of 8 (8xzoomFactor), since JPEG compression processes pixels in sets of 8. In zoom 1x and zoom 2x, src_w and src_h should reflect the actual size of the window.

Description

XPlxShmGetCImage() gets a compressed image and places it in the shared memory buffer, then returns a pass/fail status. If the server and client programs are local to each other (share the same system), you can use this call with the other XPlxShm* calls to eliminate the need to copy image data over the network for the client's use.

Note: You must allocate a shared memory segment before passing it to this function

If you are writing your own application supporting HP with shared memory (Parallax software version 9.3 or higher for HP), and if there is a possibility that you may use software decompression of JPEG data, then you should search for and remove a string of garbage data (FFFFFFD0) in each JPEG frame before you write the frame. In Parallax software version 9.3 or higher for HP, MovieTool and VideoTool remove this garbage data; scomp does not. For more information, see pages 1-14, 3-42 (Xt), and C-7. Following is an example of how to search for and delete the garbage data:

/* 
 * Use the JPEG widget to compress a new image
 */
XtVaSetValues(playbackWidget, XtNgetNewImage, True, NULL);

if (0xffffffd0 == *(unsigned int*)jpegImage->data)
{
/* Some video cards return JPEG data that begins */
/* with a StartFrame marker code.  For software  */
/* decompressor compatibility, do not write these */
/* bytes into the movie file */
  offset = 4;
  jpegImage->size -= offset;
}

Note: If you are saving JFIF images, you may want to check that the image width is divisible by 16 before using XPlxShmPutCImage, and reduce the image size if needed. The reason is to make the image displayable by third party applications such as ImageMagick's "display" that require a JFIF image width that is divisible by 16. See MovieTool (HP version 9.3 or higher) for an example of how to do this automatically.

Errors

BadDrawable
BadGC
BadMatch

Related Functions

MakeQTables(), XPlxCreateCImage(), XPlxDestroyCImage(), XPlxGetCImage(), XPlxPutCImage(), XPlxPutTable().

XPlxShmPutCImage()

Takes an image from shared memory buffer and decompresses it, then returns a pass/fail status.

Usage

Status XPlxShmPutCImage(dpy, d, gc, image, src_x, src_y, src_w, src_h, dst_x, dst_y, dst_w, dst_h, flag);

Display *dpy;
Drawable d;
GC gc;
XPlxCImage *image;
int src_x, src_y;
unsigned int src_w, src_h;
int dst_x, dst_y;
unsigned int dst_w, dst_h;
int flag;

Arguments

*dpy Specifies a pointer to the Display structure

d Specifies the Drawable (which must be a window) to get the compressed image data from

gc Specifies the Graphics Context

image Specifies the compressed image to be displayed

src_x, src_y Specifies the starting point for decompression of the source image

src_w, src_h Specifies the width and height of the source image In zoom 1x and zoom 2x, src_w and src_h should reflect the actual size of the window. Example: src_w = windowWidth/zoomFactor.

dst_w, dst_h Specifies the width and height of a destination window, In zoom 1x and zoom 2x, dst_w and dst_h should reflect the actual size of the window.

flag Specifies whether the source image should be squeezed (set to 1) or cropped (set to 0) in the destination window.

Description

XPlxShmPutCImage() takes an image form the shared memory buffer and decompresses it, then returns a pass/fail status. If send_event is True, prompts the server to send an event to indicate "Buffer can now be written to--the stored data has been displayed." If the server and client programs are local to each other (share the same system), you can use this call with the other XPlxShm* calls to eliminate the need to copy image data over the network for the client's use.

Errors

BadDrawable
BadGC
BadMatch

Related Functions

MakeQTables(), XPlxCreateCImage(), XPlxDestroyCImage(), XPlxGetCImage(), XPlxPutCImage(), XPlxPutTable().

Utility Functions

The following pages describe the utility functions that are defined in our Xlib extension library, libXPlx.a.

These functions (available only in recent softare releases) support multiple Parallax video cards in one workstation, sleep, and finding a TrueColor visual.

Function	Summary
XPlxFindMathcingSignal()	Video In/Out: Finds a video signal of a specified type
XPlxGetCurrentHardwareInstance()	Multi-card: Gets the default video card for the specified display
XPlxGetHardwareInstances()	Multi-card: Gets the number of Parallax video cards available on the specified display
XPlxGetVideoVisual()	TrueColor: Attempts to find a TrueColor visual for the specified display
XPlxQueryHardware()	Multi-card: Gets information about a specific Parallax video card
XPlxSelectHardwareInstance()	Multi-card: Sets the default Parallax video card for the specified display
XPlxSelectWindowHardwareInstance()	Multi-card: Associates a window with a Parallax video card instance
XPlxSetDrawableToAdapter()	Multi-card: Associates a window with a Parallax video card instance
XPlxSleep()	Sleep: Pauses the application for a specified time

XPlxFindMatchingSignal()

Parallax software for Sun Solaris 2.5 and version 9.3 for HP or higher: Finds a video signal of a specified type.

Usage

void XPlxFindMatchingSignal(Channel, Standard, Format, Instance)

int Channel;
int Standard;
int Format;
int Instance

Arguments

Channel Specifies the video input channel (Input_1 or Input_2). Input_2 is only available for XVideo-Xtra/VIO/RGB/700 users.

Standard Specifies the video signal standard (NTSC, PAL, or SECAM; the USA standard is NTSC).

Format Specifies the video signal format (Composite, S-VHS, RGB, or YUV formats). S-VHS is available only for XVideo-Xtra/VIO/700 users. RGB and YUV are available only to XVideo-RGB users, only on Input_2.

Instance Specifies which instance of a given signal type should be used if multiple instances are available. For the Sun video framebuffer platform, always set this to 0. On the HP and Sun video overlay cards, there are two NTSC Composite inputs available on channel PLX_INPUT_O.

Description

Given a pointer to a plxIO data structure, and a video signal specification (channel, standard, format, and instance), this function returns True if the given video signal type is available on the hardware being controlled.

XPlxGetCurrentHardwareInstance()

Parallax software for Sun Solaris 2.5 and version 9.3 for HP or higher: Gets the default video card for the specified display.

Usage

int XPlxGetCurrentHardwareInstance(display)

Display *display

Arguments

*display Specified a connection to the X server; returned from XOpenDisplay()

Returns

Number The instance number of the Parallax Graphics video card that is currently the default for the specified display.

Description

XPlxGetCurrentHardwareInstance() gets the value out of the display structure that was inserted with a call to XPlxSelectHardwareInstance(). If XPlxSelectHardwareInstance() was not called prior to the call to XPlxGetCurrentHardwareInstance(), this funciton simply returns 0.

XPlxGetHardwareInstances()

Parallax software for Sun Solaris 2.5 and version 9.3 for HP or higher: Gets the number of Parallax Graphics video cards available on the specified display.

Usage

int XPlxGetHardwareInstances(display)

Display *display

Arguments

*display Specified a connection to the X server; returned from XOpenDisplay()

Returns

Number The total number of Parallax Graphics video cards that are available on the specified display.

Description

XPlxGetHardwareInstances() queries the adaptor list looking for Parallax Graphics video cards. This function returns the number of Parallax Graphics video cards available on the specified display.

XPlxGetVideoVisual()

Parallax software for Sun Solaris 2.5 and version 9.3 for HP or higher: Attempts to find a TrueColor visual for the specified screen and display.

Usage

XVisualInfo* XPlxGetVideoVisual(screen, display)

int screen;
Display *display

Arguments

screen Specifies a screen; returned from DefaultScreen (display).

*display Specified a connection to the X server; returned from XOpenDisplay()

Returns

XVisualInfo* Information about the visual found

Description

Attempts to find a TrueColor visual for the Screen and Display passed in as arguments. If a TrueColor visual is not found, the DefaultVisual for that Screen and Display is returned. In either case, the visual information returned should be sufficient for use in creating windows for video operations.

XPlxQueryHardware()

Parallax software for Sun Solaris 2.5 and version 9.3 for HP or higher: Gets information about a specific Parallax Graphics video card.

Usage

XPlxHardwareInfo* XPlxQueryHardware(display, window, gc)

Display *display;
Window window;
GC gc;

Arguments

*display Specified a connection to the X server; returned from XOpenDisplay()

window Specifies the window

gc Specifies the Graphics Context.

Description

XPlxQueryHardware() gets the hardware information about the video card attached to the specified window. Before this call is made, XPlxSelectWindowHardwareInstance() should be called to select the video card attached to the specified window.

XPlxSelectHardwareInstance()

Parallax software for Sun Solaris 2.5 and version 9.3 for HP or higher: Sets the default Parallax Graphics video card for the specified display.

Usage

Bool XPlxSelectHardwareInstance(display, hwInstance)

Display *display;
int hwInstance;

Arguments

*display Specified a connection to the X server; returned from XOpenDisplay()

hwInstance Specifies which Parallax Graphics video card will be the default. This value ranges from 0 to (XPlxGetHardwareInstances()-1)

Returns

True If the call was successful.

False If the call was unsuccessful.

Description

XPlxSelectHardwareInstance() puts a value into the display structure that indicates which Parallax Graphics video card is the default. Currently, there is no way to remove the value from the display structure. Subsequent calls to this function replace the value.

XPlxSelectWindowHardwareInstance()

Parallax software for Sun Solaris 2.5 and version 9.3 for HP or higher: Maps a window to a particular Parallax Graphics video card.

Usage

Bool XPlxSelectWindowHardwareInstance(display, window, hwInstance)

Display *display;
Window window;
int hwInstance;

Arguments

*display Specified a connection to the X server; returned from XOpenDisplay()

window Specifies the window.

hwInstance Specifies which Parallax Graphics video card will be the default. This value ranges from 0 to (XPlxGetHardwareInstances()-1)

Returns

True If the call was successful.

False If the call was unsuccessful.

Description

XPlxSelectWindowHardwareInstance() ties a window to a Parallax Graphics video card instance. Subsequent calls to Parallax Graphics video libraries will perform their actions on the specified video card. This function returns True on success of False on failure. Passing in a bad hardware instance will cause a failure.

XPlxSetDrawableToAdaptor()

Parallax software for Sun Solaris 2.5 and version 9.3 for HP or higher: Associates a window with a particular Parallax Graphics video card instance.

Usage

XPlxSetDrawableToAdaptor(display, window, adaptor)

Display *display;
Window window;
int adaptor;

Arguments

*display Specified a connection to the X server; returned from XOpenDisplay()

window Specifies the window.

hwInstance Specifies which Parallax Graphics video card to attach to the window.

Description

XPlxSetDrawableToAdaptor() associates a Parallax Graphics video card instance to a window. If multiple Parallax Graphics video cards are installed, this is one way to use multiple video cards in the same application. The Parallax Graphics libraries will use the card attached to the window that you pass into the library calls.

XPlxSleep()

Parallax software for Sun Solaris 2.5 and version 9.3 for HP or higher: Pauses the application for a specified time in microseconds.

Usage

XPlxSleep(TimeInMicroseconds)

int TimeInMicroseconds;

Arguments

TimeInMicroseconds Specifies the number of microseconds to sleep

Description

This function takes as an argument the number of microseconds to sleep, then calls select() to pause the application.