Preparation

The instructions concerning the execution of the example programs presented in this manual assume that you are working in your "current working directory." It makes no difference where your current working directory is within the hierarchical directory structure of HP-UX. (A discussion of the hierarchical directory structure used by the HP-UX Operating System is found in the A Beginner's Guide to HP-UX and the How HP-UX Works: Concepts for the System Administrator supplied with your system.)

Pertinent Files

The following table lists files that are used when writing code that uses the Display List. There are include files, which are copied into the source code via "include" statements, and there are library files, which must be linked to the object code before program execution. Note that the include files are located in the directory 〈sb-incl〉 ^[1] and the library files are located in the following directory:

〈common〉/lib  directory
for archived and shared libraries

Table 4-1 Display List Files

File Name

File Contents

dl.c.h

The header file to include in C application programs. This file need be included only once per program, right after the #include <starbase.c.h> statement: #include <dl.c.h>.

dl.f1.h

The first of two Fortran77 include files. This file needs to be included only once per program, right after the

include '〈sb-incl〉/starbase.f1.h'

statement:

include '〈sb-incl〉/dl.f1.h'

This file defines the required alias compiler directives for Display List.

dl.f2.h

The second of two Fortran77 include files. Since Fortran does not support global entities, this include file must be included in every function or subroutine that uses any Display List constants (defined via the parameter statement), right after the

include '〈sb-incl〉/starbase.f2.h'

statement:

include '〈sb-incl〉/dl.f2.h'

dl.p1.h

The first of two Pascal include files. This file, which defines Pascal constants and types, need be included only once per program, right after the ^[1]

$include '〈sb-incl〉/starbase.p1.h'$

statement:

$include '〈sb-incl〉/dl.p1.h'$

dl.p2.h

The second of two Pascal include files. This file, which defines Pascal procedure aliases, need be included only once per program: right after your const, type, and var declarations, usually right after the

$include '〈sb-incl〉/starbase.p2.h'

statement:

$include '〈sb-incl〉/dl.p2.h'$

libdl.*

Display List's device-independent functions and procedures. Needed for all programs that access Display List procedures. (Archive libraries end in .a; shared libraries end in .sl.) This file can be found in the directory 〈common〉/lib.

libdlrefs.*

Another Display List library; this can be a useful tool to use when a program interprets Display List elements generated by another program. See interpret_ele(3G). (Archive libraries ends in .a; shared library ends in .sl.) This file can be found in the directory 〈common〉/lib.

libdddl.*

The display list driver library used for device-independent display lists. (Archive libraries ends in .a; shared library ends in .sl.) This file can be found in the directory 〈common〉/lib.

^[1]The actual path name of the directory given in angle brackets depends on the file system structure; see the Graphics Administration Guide for details.

Compiling and Linking Display List Programs

The calling conventions for the programming languages C, Fortran77, and Pascal are defined for each function in the Display List Reference section of this manual.

As mentioned above, the instructions concerning the execution of the example program presented in this chapter assume that you are working in your "current working directory."

Conceptually, Starbase has two levels: device-independent and device-dependent. The high-level Starbase code provides user procedures that are device independent; they work the same way regardless of the graphics device you have. The Starbase device drivers contain the code that drives the graphics devices. Because different devices have different requirements, the drivers must be device dependent. Note that a single driver (for example, the HP-GL driver) may support several similar devices (for example, the HP 7475, HP 7550 plotters, etc.).

Starbase Libraries

Since code from both levels is required to create a usable program, the user must link both device-independent code (Starbase high-level routines) and device-dependent code (drivers) in order to generate the final object file.

The Starbase archived and shared libraries are located in the directory^[2]

〈common〉/lib

The device drivers have file names starting with "libdd". The Starbase high-level routines are libhpgfx.sl for shared libraries and libhpgfx1.a and libhpgfx2.a for archive libraries. The Starbase Display List device-independent routines are libdl.sl for shared libraries and libdl.a for archive libraries.

Take a moment and list the library files to see which libraries are available with your system.

To look at the Starbase high-level routines for archived and shared libraries, type:

ls 〈common〉/lib/libhpgfx*

To look at the device-dependent archived and shared libraries, typeTitle not available:

ls 〈common〉/lib/libdd*

Shared and Archive Libraries

Starbase Display List libraries are available in two types: archive and shared. The Starbase Display List archive library file names end with .a, while shared library file names end with .sl. These files are located in the directory

〈common〉/lib

If you have installed both versions of these files, the linker/loader program `ld' uses the shared file (ending in .sl). (To force the archive version, the environment variable LDOPTS must be set to include -a archive before compiling). See ld(1) for additional information about which library to load. Starbase libraries must not be mixed in the linking process, that is, either all libraries must be linked as archive or all libraries must be linked as shared.

Archive Libraries

The Starbase Display List archive libraries are comprised of object files which contain device-independent code (Display List procedures). The Starbase archive libraries are comprised of object files which contain device-independent code or device-dependent code (device drivers). These libraries are copied into the application object code resulting from compilation and linking. Device dependent code is comprised of the device drivers. For example, one archive device driver library is libddgcrx.a (see the HP-UX Starbase Device Drivers Manual for a detailed description of all the device drivers available). The Starbase archive device drivers must be linked at compile time for every device a particular application may possibly use.

To use archive libraries the filesets SBDL-PRG, STAR-RUN and STAR-PROG must be installed. To compile with archive libraries, set the environment variable LDOPTS to include -a archive. The environment variable can be set in your shell configuration file or interactively.

For C shell:

setenv LDOPTS "-a archive -L〈common〉/lib"

For Korn shell

export LDOPTS="-a archive -L〈common〉/lib"

To compile and link archive libraries, use the following command format^[3]:

cc example.c -I〈sb-incl〉 -o example \
  -l<device
driver> -ldl  -lhpgfx1 -lhpgfx2 -lm

The link sequence above is identical to the standard Starbase link sequence with the addition of the Starbase Display List library, -ldl. The library -ldl must precede the device-independent Starbase libraries -lhpgfx1 and -lhpgfx2 in the link sequence. The Display List device driver, if included, is treated like any other graphics device driver and linked prior to the Starbase Display List library.

Also note the presence of "-lm" in the script above. This links in the math library. This is included in the link sequence in case some of your programs use back-facing cull, shading, the camera model, or any other operations that need the math library.




	NOTE: You must match the device path, device driver, and the run-time archive library to the hardware you use. The table below shows some common match-ups.

Table 4-2 Abridged Table of Device Drivers

Device Type	Device Path	Device Driver	Run-Time Library
HP 98765	`"`〈`screen`〉`/<window_name>"` ^[1]	`"hp98765"`	`libdd98765.a`
HP 98766A (accelerator)	`"`〈`screen`〉`/<window_name>"`	`"hp98766"`	`libdd98766.a`
HP-GL	`"`〈`dev`〉`/hpgl"`	`"hpgl"`	`libddhpgl.a` and `libdvio.a`
^[1]The actual path name of the directory given in angle brackets depends on the file system structure; see the Graphics Administration Guide for details.

Shared Libraries

The Starbase and Starbase Display List shared libraries contain relocatable object code just like the archive libraries. However, the linker does not copy the object code from the library into the application object code. Instead, the linker notes which routines are called from the shared libraries.

When the application program that uses shared libraries executes, the calls to library routines are resolved by the dynamic loader libdld.sl. The necessary libraries are explicitly loaded at run-time. Thus, several application programs can "share" the same library routines, even if the applications are executing concurrently.

The Starbase Display List device-independent code is located in the file^[4]:

〈common〉/lib/libdl.sl

The Starbase device-independent code is located in the file:

〈common〉/lib/libhpgfx.sl

The Starbase device-dependent code (drivers) is located in the files:

〈common〉/lib/libdd*.sl

for example, libddgcrx.sl. The important difference between shared and archive drivers is that the linkage parameters in the compile statement for shared libraries do not include the device driver library, the dynamic loader is linked instead. In addition, the Starbase device-independent library

〈common〉/lib/libhpgfx.sl

replaces the two archive libraries:

〈common〉/lib/libhpgfx1.a

and

〈common〉/lib/libhpgfx2.a

To develop Starbase Display List programs with shared libraries the filesets SBDL-PRG, SBDL-SHLIBS, STAR-RUN, STAR-SHLIBS, and STAR-PRG must be installed on your system. To compile a program using shared libraries, use the following command format:

cc example.c -I〈sb-incl〉 -o example \
  -L〈common〉/lib -ldl -lhpgfx -lm -ldld

Note the order of the parameters -ldl -lhpgfx must be as shown.

A Makefile

The following Makefile (or a modified version thereof) will save you some typing as you compile and execute the example programs discussed in this manual.

Makefile examples are given below for both shared and archive libraries.




	NOTE: A tab is present before each `cc` statement in the following examples.

For shared libraries, create a file named Makefile to include the following^[5]:

example : find_drv.o
        cc -o example example.o -L〈common〉/lib -ldl \
          -lhpgfx -lm -ldld
 
example.o : example.c
        cc -c -I〈sb-incl〉 example.c

For archive libraries, first set the environment variable LDOPTS to:

"-a archive -L〈common〉/lib"

(see the previous discussion on archive libraries).

Create a file named Makefile to include the following:

DRIVERS=\
  <driver
file1> \
  <driver
file2> \
      .
      .
      .

  <driver
fileN>
 
example : example.o
        cc -o example example.o -L〈common〉/lib $(DRIVERS) \
          -ldl -lhpgfx1 -lhpgfx2 -lm
 
example.o : example.c
        cc -c -I〈sb-incl〉 example.c

For example, a Makefile to link the archive drivers, HP 98705, HP CRX, and HP 98766^[6]:

DRIVERS=\
  -ldd98705
  -lddgcrx
  -ldd98766
 
example : example.o
        cc -o example example.o -L〈common〉/lib $(DRIVERS)\
          -ldl -lhpgfx1 -lhpgfx2 -lm
 
example.o : example.c
        cc -c -I〈sb-incl〉 example.c

And from now on, to compile the program, locate yourself in the directory where the Makefile and program are held and type:

make

To execute the program, type the name of the executable (named by the -o option), for the above example.c program, you would type:

example

The File Descriptor

Because Starbase can support many active graphics devices simultaneously, a means must exist to distinguish between them in your programs. This is the file descriptor. When a graphics device is "opened" (declared that it is to be accessed by a program), a unique file descriptor is assigned to that device running to a window named starbase_window. For example, for a raster graphics device, the 〈fildes〉 is assigned as follows:

int fildes;
.
.
.
fildes = gopen("〈screen〉/starbase_window", OUTDEV, NULL, INIT);

Note that the device is specified by the path 〈screen〉/starbase_window. The NULL device driver parameter (for C programming, for other bindings, see gopen(3g)) allows gopen to inquire the system for the installed raster device associated with the device file. By default, the associated driver will be "accelerated" if an accelerated driver exists for the device.

The gopen example above is equivalent to^[7]:

int fildes;
.
.
.
fildes = gopen("〈screen〉/starbase_window", OUTDEV, NULL, INIT|ACCELERATED);

The flag UNACCELERATED may be OR'ed with INIT to force the unaccelerated driver (see gopen(3g)).

int fildes;
  .
  .
  .
fildes = gopen("〈screen〉/starbase_window",OUTDEV,NULL,INIT|UNACCELERATED);

For other devices the device path must be specific to the particular device file created for that device (see the HP-UX Starbase Device Drivers Manual). For devices that do not have "accelerated" drivers the ACCELERATED/UNACCELERATED flags are meaningless. In this example, the fildes variable is used in Starbase procedures to reference one raster graphics device, while other graphics devices must have their own unique file descriptors.




	NOTE: Only raster devices can be inquired, thus the `NULL` device driver parameter is valid for raster devices only. Thus, printer drivers, terminal drivers, plotter drivers, and so forth, require that a device driver name be included in the `gopen` parameter list (in place of `NULL`).

At the end of the program, the device is closed:

gclose(fildes);




	NOTE: The example programs in this manual use the environment variables `SB_OUTDEV` and `SB_OUTDRIVER`. `SB_OUTDEV` specifies the path of the device file created for the device or the graphics window to be opened by `gopen`. This file is created using mknod(2), see the HP-UX Starbase Device Drivers Manual)''. `SB_OUTDRIVER` specifies the name of the device driver. For raster devices, this parameter can be set to `NULL` (for C programs and for other bindings, see gopen(3g)). For non-raster devices this parameter must be set to the appropriate name of the associated device driver.

C

The file dl.c.h contains C compiler directives describing constants and external definitions for the Starbase Display List library. This file must be included after the Starbase include file starbase.c.h.

FORTRAN77

The file dl.f1.h contains Fortran77 compiler directives describing the parameter passing conventions for the Starbase Display List library.




	NOTE: The file `dl.f1.h` must be included before any program or subroutine declarations in each file that invokes the Starbase Display List, but after the inclusion of the Starbase include file `starbase.f1.h`. Improper operation of the Starbase Display List will occur if this file is not included.

The file dl.f2.h contains the definition of constants defined for use with the Starbase Display List. This file must be included in each subroutine or program unit that uses the constants. The include statement for this file must follow the include statement for the file starbase.f2.h. This is illustrated below^[8].

include '〈sb-incl〉/starbase.f1.h'
include '〈sb-incl〉/dl.f1.h'
program main
   .
   .                            (user
constants, etc.)
   .
include '〈sb-incl〉/starbase.f2.h  (Starbase
constants) include '〈sb-incl〉/dl.f2.h'       (Display
List constants)
   .
   .                           (remainder
of program)
   .
end
 
subroutine graphics_subroutine          
   .
   .                             (user
constants, etc.)
   .
include '〈sb-incl〉/starbase.f2.h'  (Starbase
constants)
include '〈sb-incl〉/dl.f2.h'        (Display
List constants)
   .
   .                            (remainder
of subroutine)
   .
 
end

Pascal

The file dl.p2.h contains Pascal compiler directives describing the parameter-passing conventions for the Starbase Display List library.




	NOTE: The Starbase Display List will operate improperly if the file `dl.p2.h` is not included in the proper context for procedure definitions and after the inclusion of the Starbase include file `starbase.p2.h`.

The file dl.p2.h contains Pascal constant definitions for use with the Starbase Display List. This file must be included in the constant definition part of a Pascal main program, function, or procedure. It must follow the inclusion of the Starbase constant definitions in the file starbase.p1.h. This is illustrated below.

The following is a template for a Pascal Starbase Display List application^[9].

program main(input, output);
$include '〈sb-incl〉/starbase.p1.h'$
$include '〈sb-incl〉/dl.p1.h'$      
   .
   .                 (const,
var, etc.)
   .
$include '〈sb-incl〉/starbase.p2.h'$
$include '〈sb-incl〉/dl.p2.h'$      
   .
   .                                  (procedures and functions)
   .
begin
   .
   .                (main
program)
   .
end.




	NOTE: For the following example programs: Make sure you have created a window named `starbase_window` using xwcreate(1).

A Simple Example Program in C

The following example program is a Display List version of the program of the same name in the Starbase Graphics Techniques. It draws a line from the lower left corner to the upper right corner of the default viewport of an HP graphics window. This example is presented to show what is (basically) the minimum needed to have a program that uses the Starbase Display List^[10] .

#include <starbase.c.h>                    /* don't forget Starbase definitions */
#include <dl.c.h>                     /* get Display List definitions */
#include <stdio.h>                    /* get standard I/O definitions */
 
#define AppendOff       FALSE         /* sent to "open_segment" */
#define AppendOn        TRUE          /* sent to "open_segment" */
#define DisplayOff      FALSE         /* sent to "open_segment" */
#define DisplayOn       TRUE          /* sent to "open_segment" */
 
main()                                /* file "OneLiner.c" */
{
    int fildes;                       /* file descriptor */
    extern char *getenv();            /* defines functions return type */
 
    if ((fildes = gopen(getenv("SB_OUTDEV"), OUTDEV, NULL,
      INIT)) == -1) {
        fprintf(stderr, "%s %s\\n", "Error: gopen failed using environment",
          "variable SB_OUTDEV.");
        exit(-1);
    }
    open_segment(fildes, 1, AppendOff, DisplayOff);/* open segment 1 */
    move2d(fildes, 0.0, 0.0);                   /* move to 0,0... */
    draw2d(fildes, 1.0, 1.0);                   /* ...and draw to 1,1. */
    close_segment(fildes);                      /* stop defining segment */
    refresh_segment(fildes, 1);                 /* draw segment 1 */
    gclose(fildes);
}

This is what the graphical output looks like:

Figure 4-1 The One-Liner

Now that you've written, compiled, and run a simple Display List program, we'll discuss the statements involved. The next section gets into this topic.

^[1]The actual path names of directories in angle brackets depend on the file system structure. See the Graphics Administration Guide for details.

^[2]The actual path names of directories in angle brackets depend on the file system structure. See the Graphics Administration Guide for details.

^[3]The actual path names of directories in angle brackets depend on the file system structure. See the Graphics Administration Guide for details.

^[4]The actual path names of directories in angle brackets depend on the file system structure. See the Graphics Administration Guide for details.

^[5]The actual path names of directories in angle brackets depend on the file system structure. See the Graphics Administration Guide for details.

^[6]The actual path names of directories in angle brackets depend on the file system structure. See the Graphics Administration Guide for details.

^[7]The actual path names of directories in angle brackets depend on the file system structure. See the Graphics Administration Guide for details.

^[8]The actual path names of directories in angle brackets depend on the file system structure. See the Graphics Administration Guide for details.

^[9]The actual path names of directories in angle brackets depend on the file system structure. See the Graphics Administration Guide for details.

^[10]The actual path names of directories in angle brackets depend on the file system structure. See the Graphics Administration Guide for details.

Preparation

Technical documentation

» Table of Contents

» Glossary

» Index

Pertinent Files

Compiling and Linking Display List Programs

Starbase Libraries

Shared and Archive Libraries

Archive Libraries

Shared Libraries

A Makefile

The File Descriptor

C

FORTRAN77

Pascal

A Simple Example Program in C