This Page is Still Under Construction

The XCAM Display Utility

This is one frame from a run of the drift2 rule. It demonstrates the "exploding patches" rule table. XCAM and drift2 were written by Harris L. Gilliam.

THE XCAM DISTRIBUTION

Introduction

The XCAM utility provides an X Windows display for CAM8. It uses the PipeComm package (included with the release) and the X11 Shared Memory Ximage Extension. XCAM may be compiled and used w/o the Shared Memory Ximage Extension (SHMXIE) with a slight performance decrease. You must also have TCL v7.3 and TK v3.6 installed to use XCAM.

Manifest

Included in the XCAM distribution you should have the following files:

README and CONCEPTS: Plain text versions of this web page split into two files. The README file explains how to install XCAM and the CONCEPTS file explains the programming concepts behind XCAM.
tkXCAM.c, tkXCAM.h: C source code for the XCAM widget to be used with TK.
XCAM.c, XCAM.h: Main program for XCAM.
XCAM.tcl: TCL startup file for XCAM.
blank: A X11 bitmat used to blank the mouse pointer.
pipe2file.c: Utility that XCAM uses.
testXCAM.c: Utility to test the XCAM program.
testXCAM.lst: Init file that testXCAM reads.
ppmtoimg.c: Utility for creating test image and colormap for use by testXCAM.
thanos2.img, thanos2.map: Test image and colormap.
protocol.notes: Description of the protocol that XCAM uses to communicate with the STEP software.

Installation

You should read the Makefile and set the variables at the beginning to their appropriate values. The directions are straightforward. At some latter date we will probably use a GNU autoconfigure script. After the Makefile has been changed you should type 'make all'. You will need to have installed XV version 3.0, the Oct 5, 1991 release of PBMPLUS, TCL version 7.3, TK version 3.6, the FSBox tk fileselector widget and the CAM8 library (CAMlib). We realize that this is a lot of stuff to have to separately configure and install and will be reorganizing the release to make things a simple as possible.

Testing

To test the XCAM program you should run testXCAM. It will start XCAM as a child process and send 1000 shmi and 1000 shmc commands to it. You should see an 512x512 color image of a comic book character. You will have to set the environment variable CAM8BASE to the root of the cam8 software tree (typically it is /cam8) before you run the test and in normal operation. You may use other test images with testXCAM as well. You need to save the image as an ascii ppm file and then use ppmtoimg to convert it into the format testXCAM expects. For example if you have an image in ppm format named bar.ppm you convert it as follows: ppmtoing bar bar This will produce two files in the same directory named bar.img and bar.map that contain the image and colormap data respectively. You then need to edit the testXCAM.lst file. If your new image is 256x256 the new testXCAM.lst file should read:

shmi bar.img 256 256
shmc bar.map 8   256

You may use as many image and colormap files as you like. You just need a line in testXCAM.lst for each one. The program will cycle through and use each image and colormap 1000 times in the order listed in the file. This may be usefull in computing throughput for your particular X Server and network configuration.

Bugs and Incompatibilities

There are bound to be bugs in this software and as of this release the programs have only been tested on Sun workstations. This is not too bad since the CAM8 only works with Sun workstations at this time. A few things to note however:

XCAM maintains two separate colormaps, one is the default colormap and the other is the image colormap. When the mouse pointer enters the image window XCAM askes the windowmanager to install the image colormap. When it leave the image window XCAM asks to windowmanager to install the default colormap. This is typical behavior for programs that manage multiple colormaps. However when using the twm windowmanager the image colormap may become permanently installed. This is a bug within the windowmanager code. The fix is to restart the windowmanager or inlcude a menu option to reinstall the default colormap.

PROGRAM CONCEPTS

XCAM was written to provide a display for CAM8 under the X Window System. This has a number of advantages. Using the XCAM display you can run CAM8 experiments remotely and view the results on your local display. Also you can resize the XCAM display to be as large as your physical display which allows you to view the output from large spaces. The VGA output from CAM8 only supports 512x512 pixel displays. XCAM also provides facilities for processing the images it displays using popular UNIX image utilities. The PBMPLUS package and the XV program are currently used for this purpose. This allows you to convert images from CAM8 into convienient formats for printing or later viewing.

XCAM uses the TCL interpreter and the TK widget library. XCAM is, at its core, a TK widget which can be embedded in other applications that may need to display images from CAM8. The TCL/TK, PBMPLUS and XV packages are included with this release. XCAM is configured to work with version 7.3 of TCL, 3.6 of TK, the Oct 5, 1991 distribution of PBMPLUS and version 3.0 of XV. Also we use the FSBox tk fileselector widget.

XCAM communicates with the STEP Control Program, which is a Forth interpreter extended to control CAM8, using a handshaking protocol. XCAM is meant to be run as a child process to the Forth. It reads 8 byte messages from and writes 8 byte messages to file descriptors passed to it on the command line. These file descriptors are setup by the Forth before XCAM is spawned as a child. We have adopted this as a standardized way of having external programs communicate with the Forth (and hence w/ CAM8). The command line parameters that are significant are:

-init: This file is typically XCAM.tcl and is the TCL script which defines the appearance of XCAM. If you are familiar w/ TCL you can write your own XCAM.tcl to add/remove functionality as desired.
-in: This number is the file descriptor XCAM will read from. The STEP program sends commands to XCAM via this descriptor.
-out: This number is the file descriptor XCAM will write to. The STEP program receives results and status information via this discriptor.
-fd: This number is the file descriptor the STEP program opened the CAM8 device on. It is used when memory allocated through the device drive needs to be mapped into the processes address space.

The file protocol.notes contains a descption of the messages that are passed between XCAM and the Forth. Currently XCAM works by setting up shared memory segment to hold images and colormaps. Thr Forth creates a shared memory segment for each image and colormap it wishes to display using XCAM. It then requests a XCAM descriptor by sending the appropiate "shmi" and "shmc" message and the shared memory id. Once XCAM descriptors are obtained the Forth displays images by reading data from CAM8 and writting it to these shared memory segment. When all data is in place the Forth send an "aply" message to XCAM with the descriptor to 'apply' If the descriptor matches a previously setup image the image is displayed. If it matches a colormap the colormap is installed as the current colormap. When the Forth is finished using the shared memory segments it sends a "free" message. XCAM will detach from the shared memory segment and mark the descriptor as invalid. Additionally the size of images may be specified using "glbx" and "glby" messages. Currently images default to 512x512 pixels.

Becasue XCAM is written using the TCL interpreter it is extensible. When XCAM starts up it searches the current directory for the the file .XCAMRC whuch should contain TCL source code. This code is executed by the TCL interpreter. This file can be used to add functionality to XCAM on a per user basis. You should read the documentation for TCL if you are not familiar with TCL programming. The file XCAM.tcl is used as a startup init file by XCAM and should not be chaged directly. This file contains code that is under development and will be changed in future releases. For purposes of extending XCAM you may assume that the menu structure setup in XCAM.tcl will not change radically. This will allow you to add your own menu items.

Following is a description of the functionality of the XCAM widget. You must be familiar with TCL and TK to properly use this information. The XCAM widget provides the following commands:

imagcmap: install image colomap in image window.
menucmap: install menu (default) colormap in image window.
pipe "cmnd": execute "cmnd" as a child process piping the current image to it as a xwd file.
capture numframes file: capture the next "numframes" frames as ppm files with the names "fileX", where X is a number between 0 and "numframes". If "numframes" is -1 then an unlimited number of frames are captured until this command is executed again. This command serves to toggle the frame capture facility.

You should read the XCAM.tcl file to see examples of how these commands are used. This set of commands will be refined and expanded in future releases.

The folowing is a description of the menu titles and the options available under them.

File
----
   Save as X Window Dump	Save current image as a XWD file

   Save as PPM			Save current image as a PPM file

   Save as Postscript		Save current image as a PS file

   Dump to XV			Pipe current image to XV program

   Capture 20 Frames		Capture the next 20 images as PPM files

[] Capture Unlimited Frames	Capture images as PPM files until this
				option is selected again.  The box to
				the left of the option is filled in
				when file capture is on and empty when
				it is off.

Colormap
--------
Switch to Default Colormap	Use the default colormap in the image
				window.  When the default colormap is
				in use this option will read "Switch
				to Image Colormap."


Controls
--------
* Normal Operation		Process all messages from the Forth
				normally.  This is XCAM's startup
				state.

o Ignore Display Requests	Ignore all messages coming from the
				Forth and return an "okay" message
				indicating no error.  This allows the
				current image to be "frozen" on the
				screen while the Forth continues to
				run unaware that images are no longe
				being displayed.

o Pause Display			Halt all processing of messages from
				the Forth and do not return any return
				code.  This will effectively pause the
				running of any experiment since the
				forth will be blocked while trying to
				read a reply from XCAM.  Use this
				option when you wish to "freeze" the
				display *and* keep the experiment from
				continuing.

  Resize Display		Resize the XCAM window to match the
				last x and y sizes set by the "glbx"
				and "glby" messages.

Harris L. Gilliam
Information Mechanics Group