WXPLOOP

Sections

NAME
SYNOPSIS
PARAMETERS
DESCRIPTION
FILES
SEE ALSO

NAME

wxploop - WXP loop and overlay program

PARAMETERS

Command Line	Resource	Default	Description
-h	help	No	Lists basic help information.
-df=filename	default	.wxpdef	Sets the name of the resource file.
-na=name	name	wxploop	Specifies the name used in resource file parsing.
-ba	batch	No	Run program in batch mode
-me=level	message	out2	Specifies level of messages to be displayed
-wn=window	window_num	0	Specifies the window number. This sets up a unique route between this program and WXPloop so that WXPloop can be run multiple times simultaneously.
-pd=domain	plot_domain	None	This specifies the plotting domain. The projection, aspect ratio and the domain size are specified.
-cd=commands	command	None	Specifies a list of commands to execute.
-pp=param[,param...]	plot_param	None	Specifies additional plotting parameters. See the plot_param resource for more details.
-fl=font_list	font_list	modern.fnt	Specifies a list of fonts to use in the plots.
-ct=color_table	color_table	wxp.clr	Specifies the color table to use in the plot. This maps color names to actual RGB color values.
-ti=title	title	Program name	Specifies the window title.
-ic	icon	Off	Specifies whether to open window in iconified mode.
-bg=color	background	black white for inverse plots	Specifies the background color of the window.
-ge=geometry	geometry	640x480	Specifies the window and paper geometry.
files ...	filename	None	Specifies the files to load into the WXPloop window. Specifying more than one will create a loop.

The WXPloop program is a program set up to allow multiple WXP programs to overlay graphics and produce loops. The program offers a window to other WXP programs so that their graphics can be drawn to that window. Also the program uses the concept of a pixmap which is an allocated portion of memory that emulates a window to create pseudo windows which can be looped or animated. Once WXPloop runs, a single main window can be opened, but several pixmaps can be also be created (up to 128). Sequencing through these pixmaps will give the sense of animation.

Information can be drawn onto the window or a pixmap in one of three ways:

using the annotation features of WXPloop to draw lines, text and markers
using the pixmap ID to allow another program to draw directly to that window or pixmap
importing an image file into the loop

WXPloop can be run in one of two operational modes: interactive and batch

Interactive Mode

Interactive mode allows the user to communicate with the WXPloop program, issuing commands to it via the loopset program. Once WXPloop is started, a message queue is opened allowing communications with the loopset program. This message queue key ID is a positive integer number set by the window_num resource. More than one WXPloop program can be running but each must have a unique window_num. If a queue exists for a particular window number and WXPloop is run, the program will exit with a message "Unable to create message queue". At this point, either the queue must be deleted or another window number must be picked. The "loopset alloc" command will return the next available window number after 20.

The program is initially in STOP mode and runs any commands passed through the command line (command resource). Then, the program will load into a loop, any image files specified on the command line. After the images are loaded, the program animates those images and waits for commands to be entered via loopset where pixmaps can be created and deleted, images annotated and loop parameters changed.

At any point through loopset, a window ID of the main window can be queried. This window ID can then be passed to any WXP graphics program by specifying the window device.

Example return: +8627531:8627533:800x600 or +8627531:8627533 (if size is the default 640x512)

Also, pixmaps can be created. The pixmap ID can be queried and graphics drawn directly to the pixmap by specifying its ID and size to the device resource.

Batch Mode

WXPloop can also be run in a batch mode. If the following command is entered:

   wxploop -wn=-1 -ba

By specifying a window number of -1, the WXPloop program does not open up a message queue. This alleviates the problem of having to allocate a different message queue for each WXPloop window. Obviously, this lack of interactivity limits the capability of WXPloop. This configuration is optimal for simple overlay displays and cannot be used for animation since there is no way to create pixmaps with a shell script.

The program will run those commands pass on the command line and load any images in listed on the command line. The WXPloop program opens the main window and titles the window "wxp_win". The program will then print the window ID of the main window allowing WXP programs to access that window with the window specification under the device resource.

+8627531:8627533:800x600

Then the WXPloop program will automatically background itself. This way, the window ID can be set to a shell variable and passed to another graphics program. Manual backgrounding is not necessary with "&" on the command line and is also not recommended.

The window ID information can also be written to a file if the filename is specified with the window_num resource "-wn=filename". The filename is then specified with the device resource "-de=w,,filename".

Keyboard and Mouse Controls

STOP GRAPHICS MODE
Once WXPloop is started, it defaults to STOP mode. In this mode, just the main X window is active. No animation is possible. Different images in the loop can be viewed, however. Some important mouse and keyboard commands are:

Keyboard/Mouse	Command
<RightButton>	Display next image in loop
<LeftButton>	Display previous image in loop
<MiddleButton>	Toggle to LOOP mode
<Meta>d	Delete current image in loop
<Meta>z	Zoom image around cursor 2x
<Meta>g	Saves window to a GIF file
<Meta>x	Saves window to a XWD file
<Meta>q	Quit WXPloop
<Enter>	Quit WXPloop

The cursor is a circle (X11) or arrow (Win32).

LOOP GRAPHICS MODE
In this mode, pixmaps are copied into the main window in a set order. Any information previously displayed to the main window will be destroyed. Some important mouse/keyboard commands are:

Keyboard/Mouse	Command
<RightButton>	Reduce delay between pixmaps by .1 seconds
<LeftButton>	Increase delay by .1 seconds
<MiddleButton>	Toggle to STOP mode
<Meta>z	Zoom image around cursor 2x
<Meta>g	Saves all pixmaps to GIF files
<Meta>x	Saves all pixmaps to XWD files
<Meta>q	Quit WXPloop
<Enter>	Quit WXPloop

The cursor is two arrows pointing beginning to end (X11 exchange cursor) or an up/down arrow (Win32). Zooms in loop mode are done on the fly to preserve the integrity of the original image.

Loopset Program

The loopset program allows WXPloop's parameters to be changed. A IPC channel is used to communicate with the ingest program. When the loopset program establishes a connection with wxploop, the following prompt will appear:

   Message queue opened (id:nnnnnn)
   Connected to WXPloop program
      Type help for help
   Message:1:

At this point, you may enter a WXPloop command. To see the list of WXPloop commands, check the wxploop command documentation. The loopset program continues to accept dataset commands until "quit" or "exit" commands are entered. If a valid command is specified from the resource file or command line, only that command will be processed and the program will exit.

Drawing

WXPloop allows the user to annotate images using the drawing commands available through loopset. These allow the user to draw lines, plot markers or text. There is a full range of set attribute commands to change colors, styles, sizes, etc. The drawing canvas is based on the viewport and window concept. There are 3 defined transformations that can be used:

0 - Pixel coordinate system (0-width,0-height) where 0,0 is in the upper left corner.

1 - Normalized coordinates (0-1, 0-1) where 0,0 is at the lower left and the extent is 0 to 1 for the largest side and a value less than 1 for the smaller side.

2 - Map coordinates where the mapping is based on the domain specified either through the plot_domain resource or through the "set domain" command.

Zooming Images

Images can be zoomed in either STOP or LOOP mode with <Meta>z. Each zoom enlarges the image at the cursor position 2x. There is a limit of 1024x on enlargement. In loop mode, the zoom is performed before each image is displayed in the window. These are not cached because contents of original unzoomed window may be changing during the zoom. Also, this avoids the extra memory requirements necessary to cache all the zoomed images.

Colors

WXPloop starts with no defined colors. If a color table is specified with the color_table resource, it is loaded into the program and those colors fixed. To use any other colors, a color table must be set up by directing WXPloop to read in a color table file with the "color" command. This will first, allocate those colors so that they cannot change if another program is run and second, set up those colors to be used by the internal WXPloop annotation commands.

NOTE: When plotting graphics to a WXPloop window or pixmap, it is highly recommended to allocate all colors used in the final graphic by using the "color" command. If this is not done, no colors are allocated and therefore fixed in the server's color table. Even though each WXP program allocates its own colors, these only remain allocated for the duration of each graphics program which is independent of WXPloop. Once the graphics program exits, the colors are deallocated and those colors displayed on a WXPloop window or pixmap may be changed by the next program that wishes to allocate colors. Running the "color" command in WXPloop will allocate/lock those colors in the color table. If a graphic uses multiple color table, the "color" must be run again to allocate the other color tables. This command does not deallocate any previous colors.

Saving Loops

Once a loop has been created, it can be saved to a GIF (Graphics Interchange Format used by Compuserve -- Default) or X window dump files with the save command. The specified filename is sent through the file name convention function. Keys include "%p" for program name and "%i" for frame index. Then these files can be read back into WXPloop later on and again animated. WXPloop will read and write image files for 1,4, 8, 16 and 24 bit displays. WXPloop will read any image files as long as the display WXPloop is connected to has a depth greater than or equal to the depth of the image contained in the file.

Commands

clear image
Clears the image in pixmap image. This blanks the pixmap returning it to an all black image. Image can be "win" for the window, "last" for the last image of a loop or a image number "#". If no image is specified, the current image is cleared.
clear
Clears the X window. This only clears the window and not any of the pixmap images.
colortable filename
Loads the color table in from the file filename and allocates the colors on the X server default colormap. This is a standard WXP color table file.

NOTE: It is a very good idea to load the appropriate colormap prior to running any WXP application in order lock the colors into the server. Failing to do so could result in losing color definition.
create
Creates a new pixmap to which data may be drawn. This pixmap is appended to the end of the current loop. If there are no images currently in the loop, the program will go from STOP mode to LOOP mode.
create pixmap
Creates a new pixmap just as the create command does. The difference is that the response is the window ID, pixmap ID and size.
Example: +8627531:8627533:800x600 or +8627531:8627533 (if size is the default 640x512).
delete image
Deletes the current image and pixmap from the loop. All remaining images are moved up in the loop one position. Image can be "last" for the last image of a loop or a image number "#". If no image is specified, the current image is deleted.
goto image
Goes to image number image. Image can be "win" for the window, "last" for the last image of a loop or a image number "#"
kill
This kills the WXPloop program. This involves freeing all the pixmaps and graphics contexts, destroying the window, deleting the message queue and exiting the WXPloop program.
line x1,y1 x2,y2
Draws a line from x1,y1 to x2,y2.
load image filename [x,y]
Loads an image from filename into image image. If an image already existed at that location, it is overwritten. An optional title may be defined. These titles are useful in labeling the image as to its contents. The colors are compressed and allocated (fixed) before copying to image. Image can be "win" for the window, "last" for the last image of a loop or a image number "#". An optional location can be specified.
loop
Toggles the loop from looping to stopped.
mark x,y
Draws a marker at x,y
open [name]
Opens the window frame for drawing and plotting. The window must be opened prior to any plotting or errors occur. The window name may be specified with name.
overlay image filename [x,y] [back]
Overlays an image from filename on top of image image. A bitmap is created based on all BLACK pixels contained in the overlay image, so that all areas in the overlay image that were black are now transparent. The colors in the overlay image are compressed and allocated (fixed) before overlay. Image can be "win" for the window, "last" for the last image of a loop or a image number "#". An optional location can be specified. Also, a background color can be specified to set transparency.
query pid
Returns the process ID of the WXPloop process.
query last
Returns the index of the last image in the loop
query num
Returns the number of images in the loop.
query window_id
Returns the base window ID, draw window ID and size.
Example: +8627531: 8627533:800x600 or +8627531: 8627533 (if size is the default 640x512).

quit
Exits loopset program.
save image filename
Saves the image image to the file filename in the specified image file format (XWD or GIF). Image can be "win" for the window, "last" for the last image of a loop, "all" for all images in a loop or a specific image number "#". The filename is sent through the file name convention function. Keys include "%p" for program name and "%i" for frame index.
set delay image delay
Sets the loop delay in seconds. This will change the image end delay for all images in the loop except for the last image whose delay is set by set pause. Image can be "win" for the window, "last" for the last image of a loop or a image number "#". If no image is specified, the current image is set. (Default: 0.5 seconds)
set direction backward
Sets the loop direction to backward or essentially reverses the flow of the loop. In this case, the loop will proceed through the loop from highest image number to lowest.
set direction forward
Sets the loop direction to forward. In this case, the loop will proceed through the loop from lowest image number to highest.
set direction alternating
Sets the loop direction to alternating. In this case, the loop will proceed through the loop from lowest image number to highest and then reverse going highest to lowest and so on.
set domain domain
Sets the plotting domain for the loop. This should correspond to the value of the plot_domain resource. This may be queried at a later time for applications wishing to overlay information or add new images to the loop.
set draw image
Sets the drawing window or pixmap for all annotation. If the draw window is the main window, image is "window" (DEFAULT), otherwise, it is the desired image number. This is useful for scripts that need to annotate on multiple pixmaps. Image can be "win" for the window, "last" for the last image of a loop or a image number "#". If no image is specified, the current image is set.
set line color color
Sets the line color to an established color name. All subsequent lines drawn by the user will be in this color.
set line style style
Sets the line style to style. Valid styles are solid,dash,doubledash.
set line width width
Sets the line width to width pixels.
set mark color color
Sets the marker color to an established color name. All subsequent lines drawn by the user will be in this color.
set mark size size
Sets the marker size to size.
set mark style style
Sets the marker style to style. Valid styles are pnt,plus,star,circle,x,square,tri,itri,dot
set mark width width
Sets the marker width to width pixels.
set name name
Sets or changes the window name which is displayed in the title bar of the X window.
set output type
Sets the output file type to gif (Default) or xwd.
set pause pause
Sets the delay in seconds for the last image in the loop. (Default: 1.0 seconds)
set size widthxheight
Sets the size of the window to be used by WXPloop. (DEF: 640x512)
set text alignment align
Sets the text alignment. The alignment is a 2 character sequence that specifies horizontal and vertical alignment. The first character is horizontal which can be either left, center or right. The second character is the vertical alignment which can be upper, top, center, base or lower. All subsequent text entered by the user will be drawn left, center, or right aligned to the starting position.
set text color color
Sets the text color to an established color name. All subsequent text entered by the user will be in this color.
set text expan expansion
Sets the text expansion factor to expansion. This specifies the relative horizontal size of the text.
set text font name
Sets the text font to name. The font name is either the alias in the wxp.fnl file or the font number, The font is read in and used as the font for all subsequent text commands. The default font is "modern.fnt".
set text height height
Sets the text height to height pixels. This specifies the actual height of the text from baseline to cap.
set text width width
Sets the text width to width pixels. This specifies the width of the lines used to draw the text. Setting this to a value greater than 1 makes the text bold.
set viewport x1,y1 x2,y2
Sets the viewport extent to x1,y1 x2,y2. This is the limits of the plotting area and is expressed as a number between 0 and 1. This is also referred to as the clipping rectangle.
set window x1,y1 x2,y2
Sets the window coordinates to x1,y1 x2,y2. This is the actual plotting coordinate system that will be mapped to the viewport.
start
Starts the loop.
step
Single steps the loop.
stop
Stops the loop.
text x,y text
Displays the text text on the window at the position x,y. The text is centered at this position.
update
Updates the window. Use this after generating a graphic to the window.