Chapter 4: Motif Functions 4








Parallax Graphics provides convenience functions for Motif that support building cascading menus for selecting video inputs and outputs. These input/output menus match the inputs and outputs available through Parallax video cards. These functions are available to developers on Sun Solaris 2.5, and Parallax version 9.3 for HP-UX or higher releases. (Some sample programs are available for earlier releases). This chapter includes:
Overview
Source Code for Applications
Source-Code for Example Programs
Include and Library Files
Usage, Makefile, and Imakefile Support
Motif Convenience Functions

Overview


For Motif developers, we provide sample programs and convenience functions for video input and output cascading menus.

The Motif convenience functions are provided to make it easier to write an application that provides user selection of live video or video output. This functionality is general, and without these Motif functions it could require large amounts of development time and application code. Also, users of Parallax Graphics video boards will benefit if this sort of user interface component looks the same (or at least similar) on all of our supported platforms and in all applications.

Parallax Graphics has developed two convenience functions to create cascading menus for selection of video input and video output: PlxCreateInputCascade() and PlxCreateOutputCascade(). We also provide supporting functions.


Source Code for Applications


We provide source-code for our applications, VideoTool and MovieTool, which demonstrate how to program with the Parallax Motif convenience functions. The source files for the application programs are located in $PARALLAX_HOME/src in the following sub-directories:

Table 1-1 Application locations within $PARALLAX_HOME/src:
Applications Summary Source Location
MovieTool Sun Solaris 2.x and HP-UX: Captures and plays back MovieTool format movies with audio in real-time.
/motif/MovieTool
VideoTool Sun Solaris 2.x and HP-UX: Displays live video (up to two simultaneously for XVideo), captures still images, adjusts color settings 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 Motif with Parallax video cards, we provide simple soruce-code example programs that can be run from the UNIX command line. These sample programs are not as carefully built and tested as the application programs, but do provide useful brief examples 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 wnat to use (See summaries below). See how the program works (Multimedia User's 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 subdirectories:

Table 1-2 Sample program locations within $PARALLAX_HOME/src:
Sample Program Summary Source File Name and Location
fcomp Sun and HP version 9.3 or higher: Displays live video, compresses it, saves it to a file, then decompresses and displays it.
/motif/file_comp/fcomp.c
fixMovieQ Sun Solaris 2.5 and HP version 9.3 or higher: Corrects the JPEG compression Q table which was incorrect in earlier releases (version 9.1 for JP and Solaris 2.4 and earlier releases.
/utils/fixMovieQ.c
scomp Sun and HP version 9.3 or higher: Displays live video, compresses it, and decompresses it into another window, while varying the Q factor and observing the change in image quality. Uses shared memory.
/motif/slider_continuous_comp/scomp.c
tcomp Sun HP version 9.3 or higher: Displays live video, compresses it, sends it over a network, and decompresses and displays it at the other end in real-time (like a videoconference prototype). Can run two tcomp sessions as bi-directional networked video.
/motif/teleconference_comp/tcomp.c
videoIcon Sun Overlay (XVideo Xtra) and HP version 9.3 or higher: Displays a small live video window inside an icon.
/motif/example/videoIcon.c

Include and Library Files


Programs developed with the Motif convenience functions should include the <XPlxExt.h> and <IOCascade.h> files--along with standard <stdio.h>, <X11/Xlib.h>, and other include files-- and should be compiled with the Parallax Motif, Xt, and Xlib library files, libXmPlx.a, libXtPlx.a, libXPlx.a, and 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 <IOCascade.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, HP version 9.3, or later: 
cc  -L$(PARALLAX_HOME)/lib -lXmPlx -lXtPlx -lXPlx -lXv -lXext -lXt -lX11 -lm

Parallax software for Sun Solaris 2.4 or earlier: 
cc  -L$(PARALLAX_HOME)/lib -lXmPlx -lXTvid -lXvid -lXext -lXt -lX11 -lm

Parallax software for HP-UX version 9.2 or earlier: 
cc  -L$(PARALLAX_HOME)/lib -lXmPlx -lXTvid -lXvid -lXv -lXext -lXt -lX11 -lm
Note: Not available for SunOS 4.1.x/X11R5 version 1.2.
Note: The user must set a site-specific environment variable to successfully compile the makefiles. PARALLAX_HOME shoudl point to 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 application 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. -I$(INCLUDESRC) -I$(MINCLUDESRC) -I$(PLXINCLUDESRC)
DEPLIBS  = $(PlxXmDepLib) $(XmClientDepLibs)
LOCAL_LIBRARIES = $(PlxXmLib) $(XpmLibrary) $(XmClientLibs)
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 an library files, please see Appendix A: Include and Library Files.

For a description of the Parallax variables that can be used with Xt resources 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).

The Parallax Xt Widgets rely on standard Xt events and messages, which are documented in standard Xt publications from O'Reilly & Associates.

Motif Convenience Functions


The following pages describe the convenience functions that are defined in our Motif extension library, libXmPlx.a.

These convenience functions (available only for Sun Solaris 2.5 and HP version 9.3 or higher) create cascading menus that match available hardware capabilities for selecting video input and output.

Function Summary
PlxChannelToInput() Video Input Menu: Converts a hardware instance and digitizer description to a digitizer number
PlxChannelToOutput() Video Output Menu: Converts a hardware instance and digitizer description to a digitizer number
PlxCreateInputCascade() Video Input Menu: Creates a video input selection based on the hardware structure that is passed in.
PlxCreateOutputCascade() Video Output Menu: Create an output selection based on the hardware structure that is passed in.
PlxInputCascadeGetChild() Video Input Menu: Returns a widget from the InputCascade widget hierarchy.
PlxInputToChannel() Video Input Menu: Converts a digitizer number to a hardware instance and digitizer description.
PlxOutputCascadeGetChild() Video Output Menu: Returns a widget from the OutputCascade widget hierarchy.
PlxOutputToChannel() Video Output Menu: Converts a digitizer number to a hardware instance and digitizer description.
Note: These Motif functions are only available for Solaris 2.5 (Sun framebuffer and overlay) and for HP version 9.3 or higher.

PlxCreateInputCascade()


.
Parallax software for Solaris 2.4 or version 9.2 for HP or higher: Creates an input selection menu based on the hardware structure that is passed in.
Usage 
PlxInputCascade	*PlxCreateInputCascade(menuParent, formatParent,
					instanceParent, standardParent,
					plxio, callbackProc)
	Widget		menuParent;
	Widget		formatParent;
	Widget		instanceParent;
	Widget		standardParent;
	plx_IO		*plxio;
	XtCallbackProc	callbackProc;

Arguments 
menuParent
Specifies the parent of the resulting widget hierarchy. Usually, this will be a pulldown menu. 
formatParent
Specifies the parent of the format menu. Usually, this is not used. 
instanceParent
Specifies the parent of the instance menu. Usually, this is not used. 
standardParent
Specifies the parent of the standard menu. Usually, this is not used. 
plxio
Specifies the Parallax Hardware structure to use in building the input menu. You can get this from XPlxQueryConfig(). If you are using the VideoIn widget, you can use the XtNhardwareParams resource to get this pointer. 
callbackProc
Specifies the function that will be called when an input menu button is selected by the user.
Returns 
PlxInputCascade*
This structure describes the menu that is generated by PlxCreateInputCascade().
Description

PlxCreateInputCascade() creates an input selection menu based on the hardware structure that is passed in. This simplifies the task of providing an easy to use menu that contains only the selections that are supported by the installed hardware. This function also creates a "First Available" button for the user's convenience.

formatParent, instanceParent, and standardParent are arguments that allow the different levels of selection (video format, wire instance, and video standard) to be placed in different interface components. If you choose not to use this feature, simply pass a NULL value for these arguments.

callbackProc specifies the function to be called when one of the buttons from the InputCascade is selected. This callback procedure will usually be used to select the appropriate video signal. Here is an example of how this callback could be written: 
void callbackProc(Widget w, XtPointer clientData, XtPointer callData)
{
  signalSpecvideoSignal;

  if(clientData == (XtPointer)NULL)
  {
    /*
     * First Avaliable button was pressed.  In this simple example,
     * we will start Input 0, Composite, wire instance 0, NTSC.
     */
    videoSignal.s.channel = PLX_INPUT_0;
    videoSignal.s.format = PLX_COMP;
    videoSignal.s.instance = 0;
    videoSignal.s.standard = PLX_NTSC;
  }
  else
  {
    /*
     * A selection was made by the user.  Extract the user's selection
     * from the return value.
     */
    videosignal.i = (unsigned int)clientData;
  }
  XPlxVideoInputSelect(display, window, gc, PlxInputToChannel[videoSignal.s.channel],
                       videoSignal.s.standard,     
		       (videoSignal.s.instance<<16) | videoSignal.s.format,
		       PLX_RGB24);
}


After a call to PlxCreateInputCascade(), several functions may be used to translate between inputs and channels. Input refers to the digitizer that digitizes the video signal. Channel contains the input information, but also includes which Parallax video board the input is on. Inputs range from PLX_INPUT_0 to PLX_INPUT_7 to identify digitizers on multiple boards. Channels are a composite of hardware instance and digitizer number (channel = (hwInst<<16) | Input, Input = (PLX_INPUT_0 | PLX_INPUT1)). The callback function from the input cascade will provide the input number. The VideoIn widget and the XPlxcalls expect a channel number (hardware instance and digitizer description).

The following arrays are helpful for using multiple video cards on a system, and currently work only for HP version 9.3 or higher:

PlxInputToChannel[] is an array that helps you convert the Input digitizer number to a hardware instance and digitizer description. For example, to convert PLX_INPUT_3 to a hardware instance and digitizer description to pass in to XPlxVideoInputSelect(), do this: 

channel = PlxInputToChannel[PLX_INPUT_3];

PlxChannelToInput[] does exactly the opposite. That is, you can convert a hardware instance and digitizer description to an Input digitizer number. For example, to find the Input number associate with the second video digitizer on the third Parallax video board, use this command: 
input = PlxChannelToInput((3 << 16) | PLX_INPUT_1);

Note: PlxInputToChannel[] and PlxChannelToInput[] can only be used after a call to PlxCreateInputCascade().
See Also
PlxInputCascadeGetChild()

PlxCreateOutputCascade()


.
Parallax software for Solaris 2.4 or version 9.2 for HP or higher: Creates an output selection menu based on the hardware structure that is passed in.
Usage 
PlxOutputCascade	*PlxCreateOutputCascade(menuParent, formatParent,
					instanceParent, standardParent,
					plxio, callbackProc)
	Widget		menuParent;
	Widget		formatParent;
	Widget		instanceParent;
	Widget		standardParent;
	plx_IO		*plxio;
	XtCallbackProc	callbackProc;

Arguments 
menuParent
Specifies the parent of the resulting widget hierarchy. Usually, this will be a pulldown menu. 
formatParent
Specifies the parent of the format menu. Usually, this is not used. 
instanceParent
Specifies the parent of the instance menu. Usually, this is not used. 
standardParent
Specifies the parent of the standard menu. Usually, this is not used. 
plxio
Specifies the Parallax Hardware structure to use in building the input menu. You can get this from XPlxQueryConfig(). If you are using the VideoIn widget, you can use the XtNhardwareParams resource to get this pointer. 
callbackProc
Specifies the function that will be called when an input menu button is selected by the user.

Returns 
PlxOutputCascade*
This structure describes the menu that is generated by PlxCreateOutputCascade().
Description

PlxCreateInputCascade() creates an output selection menu based on the hardware structure that is passed in. This simplifies the task of providing an easy to use menu that contains only the selections that are supported by the installed hardware.

formatParent, instanceParent, and standardParent are arguments that allow the different levels of selection (video format, wire instance, and video standard) to be placed in different interface components. If you choose not to use this feature, simply pass a NULL value for these arguments.

callbackProc specifies the function to be called when one of the buttons from the OutputCascade is selected. This callback procedure will usually be used to select the appropriate video signal. Here is an example of how this callback could be written: 
void callbackProc(Widget w, XtPointer clientData, XtPointer callData)
{
  signalSpecvideoSignal;

  /*
   * A selection was made by the user.  Extract the user's selection
   * from the return value.
   */
  videosignal.i = (unsigned int)clientData;
  }
  XPlxVideoOutputSelect(display, window, gc, PlxOutputToChannel[videoSignal.s.channel],
                       videoSignal.s.standard,     
		       (videoSignal.s.instance<<16) | videoSignal.s.format,
		       PLX_RGB24);
}

After a call to PlxCreateOutputCascade(), several functions may be used to translate between outputs and channels. Output refers to the digitizer that digitizes the video signal. Channel contains the output information, but also includes which Parallax video board the output is on. Outputs range from PLX_INPUT_0 to PLX_INPUT_7 to identify digitizers on multiple boards. Channels are a composite of hardware instance and digitizer number (channel = (hwInst<<16) | Output, Output = (PLX_OUTPUT_0)). The callback function from the input cascade will provide the output number. The VideoIn widget and the XPlxcalls expect a channel number.

The following arrays are helpful for using multiple video cards on a system, and currently work only for HP version 9.3 or higher:

PlxOutputToChannel[] is an array that helps you convert the Output digitizer number to a hardware instance and digitizer description. For example, to convert PLX_OUTPUT_3 to a hardware instance and digitizer description to pass in to XPlxVideoOutInputSelect(), do this: 
channel = PlxOutputToChannel[PLX_OUTPUT_3];

PlxChannelToOutput[] does exactly the opposite. That is, you can convert a hardware instance and digitizer description to an Output digitizer number. For example, to find the Output number associate with the output digitizer on the third Parallax video board, use this command: 
output = PlxChannelToOutput((3 << 16) | PLX_OUTPUT_0);

Note: PlxOutputToChannel[] and PlxChannelToOutput[] can only be used after a call to PlxCreateOutputCascade().
See Also
PlxOutputCascadeGetChild()

PlxInputCascadeGetChild()


.
Parallax software for Solaris 2.5 or version 9.3 for HP or higher: Returns a widget from the InputCascade widget hierarchy.
Usage 
Widget PlxInputCascadeGetChild(parent, childId)
	Widget 	parent;
	int	childId;

Arguments 
parent
Specifies the parent that was passed into PlxCreateInputCascade(). 
childId
Specifies the child by the Input, Format, Instance, and Standard.
Description

PlxInputCascadeGetChild() returns a widget form the InputCascade widget hierarchy. This is useful if you would like to create a customized input menu.
The requested child is specifies by or'ing the Input, Format, Instance and Standard together. For example, if you would like to make the Input2/S-VHS/1/PAL widget insensitive, do this: 
Widget	button;
button = PlxInputCascadeGetChild(parent,
	  IOC_Input2 | IOC_FormatYC | IOC_Instance0 | IOC_StandardPAL)
XtSetSensitive(button, False);


All of the widget identifiers start with IOC_. There are identifiers for the menu panes as well. The identifiers can be found in $PARALLAX_HOME/include/IOCascade.h

PlxOutputCascadeGetChild()


.
Parallax software for Solaris 2.5 or version 9.3 for HP or higher: Returns a widget from the OutputCascade widget hierarchy.
Usage 
Widget PlxOutputCascadeGetChild(parent, childId)
	Widget 	parent;
	int	childId;

Arguments 
parent
Specifies the parent that was passed into PlxCreateOutputCascade(). 
childId
Specifies the child by the Output channel, Format, Instance, and Standard.
Description
PlxOutputCascadeGetChild() returns a widget form the OutputCascade widget hierarchy. This is useful if you would like to create a customized input menu.
The requested child is specifies by or'ing the Output channel, Format, Instance and Standard together. For example, if you would like to make the Output/S-VHS/1/PAL widget insensitive, do this: 
Widget	button;
button = PlxOutputCascadeGetChild(parent,
	  IOC_Output | IOC_FormatYC | IOC_Instance0 | IOC_StandardPAL)
XtSetSensitive(button, False);


All of the widget identifiers start with IOC_. There are identifiers for the menu panes as well. The identifiers can be found in $PARALLAX_HOME/include/IOCascade.h