SLD [ Intro | Pubs | RunInfo | Workbook | Software | SLACVX | Search ]

The SLD Event Display Additions Manual

Adding Objects

In the SLD event display system, objects (for example a MCPART track or a drawing of the WIC) are built out of simpler parts called "display primitives" (points, lines, circles and so forth). For each object type, there is a prepmort file, called a "draw routine," which tells how to build the object out of these primitives.

To add a new object type to the SLD event display, you must write a new draw routine, assure that the new routine is loaded, and add a DSPUSRT bank.

Writing a New Draw Routine

To write a new draw routine, take the overall structure from an existing draw routine. Good examples are the DST drawing routines. These have file names of the form PHDxxxx. PHDPART, for example, draws DST particle tracks, PHDKAL draws DST kal clusters.

Copy the head of the draw routine from PHDPART. There will always be a single argument, a pointer to DSPOTYP.

Most draw routines loop over many banks of a given kind. For example, PHDPART loops over many PHPART banks. For each PHPART bank, it creates one DSPOBJ bank. Fill the DSPOBJ bank as follows:

Having set up the DSPOBJ bank, the draw routine should then create the display primitive banks that describe the object. The number and type of display primitive banks depends on what you want to draw. For example, the draw routine PHDPART, draws a particle track by creating a single polyline primitive bank. The draw routine DSPDSCR, draws a CRID outline by creating five circle primitive banks and one polyline primitive bank.

In each case, you JZBADD the relevant type of primitive bank and then fill in the data for the bank (just look at the templates and the examples to see what's needed).

The UGOPTN data should correspond to the options listed in the SLAC Unified Graphics System Programming Manual (CGTM 203). Here one specifies color, line style, text size and blink.

The SLD event display allows three special mark styles for points. They are selected by setting the MARK= option in the UG option string (the UG manual says this is not supported, but the SLD event display gets around this).

Mark styles 1,2 and 3 can have their size changed by the SIZE= option in the UG option string (default .01). Note that at draw time this size is scaled by the current zoom. This means when you do a DSP ZOOM and then a DSP DRAW, the marks themselves will not change size. Also note that these complicated mark styles result in slower drawing. If you have a great many objects to draw, keep the style simple.

The display system contains logic to keep graphics buffers from overflowing. However, you can get into trouble if you make a single display primitive very very large. In such cases, part of your picture may not appear. To avoid this, break things up so that, for example, no single DSPOPPT or DSPOPLN contains over 1000 points.

It's good form for the draw routine to start off with a check that the relevant data exists. Issue an error message if there is no data to draw. Otherwise, when you go to draw the object and the display responds by doing nothing, you'll wonder what's wrong. See how it's done in KALDRFC. A JZPIDX and a check on J$NUMBER does the trick. You'll be sorry if you leave out this check.

Assuring that the New Routine is Loaded

The draw routines are not called explicitly by any other routine. They are instead invoked in an indirect system known as "call by address." Consequently, the loader will not automatically link in your new draw routine. You must explicitly load the routine via a TEXT = statement in your SANECTRL file or an obj_files = statement in your CETI BUILD file.

For large packages of additional display code, many draw routines can be loaded via a single dummy reference routine. For example, to load the DST display package, you need only load the file PHRDSP PREPMNLB which in turn contains references to all the other DST display routines. You can set up a similar dummy reference system for any other new batch of draw routines.

( On the IBM, files such as PHRDSP PREPMNLB are not loaded directly but are loaded via an INCLUDE = statement that pulls in this file and allows room to do other special things at the same time.)

Adding a DSPUSRT Bank

To tell the display system that there is a new object type, you must add a DSPUSRT bank. Take, as your example, the DSPUSRT parts of the PHUDSP CONSTANT file. This data adds all the DST object types to the display code. (Ignore the other parts of the PHUDSP CONSTANT file. You won't need this to create new object types).

Groups of closely related object types are collected into what are called "object groups." An object group can contain anywhere from 1 to 32 object types. You create one DSPUSRT bank for each object group. The bank then contains a separate TYPE block for each object type.

By default, your draw routine is called only once per event no matter how often the user redraws (unless they issue a DSP RECALC command). If you want your draw routine to be called more often, set one of the following flags.

When you run your job, pull in your new object types by issuing the IDA command DSP USERDATA followed by the filename of the file that contains the DSPUSRT banks.

For each DSP USERDATA statement, you should get a message telling you that the object types have been loaded. If you then do DSP SHOW TYPES, you should see your new object types.

Note that due to a bug in the GET system, DSP USERDATA will give no message at all if it fails to find the constant file name that you specified. So if your new object types don't appear in DSP SHOW TYPES, check whether you've correctly spelled the constant file name.

If DSP SHOW TYPES shows your new object types, you have succeeded. You can add the objects via a DSP ADD command. If you are using the display in 3D interactive mode, the new object types will appear in the data selection menu and you can add them from there. The next time you do a DSP DRAW, your draw routine will be called and the primitive banks that it creates will be drawn to the screen.

Joseph Perl
25 September 1997