NAME

starbase − Starbase Graphics Library description

DESCRIPTION

The Starbase Graphics Library consists of procedures used to generate graphics pictures and text. 

The Starbase Graphics Library provides a high-performance interface to HP graphics hardware and other selected graphics peripherals.  These library routines can be used in C, Pascal and FORTRAN77 programs. 

NOTE:  Performance will be best for C programs.  C can make use of fast macros, which use procedure pointers to make subroutine calls. 

In addition to the standard ANSI CGI functions, Starbase provides asynchronous input functions, 3-dimensional transformations, and access to many device-dependent hardware features. 

CAUTION:  The Starbase libraries are only Level 0 thread safe.  This means that threaded programs may not make calls to these libraries. 

LINKING STARBASE PROGRAMS

It is extremely important that link files be specified in the following order:

 driver(s), window_library location, window_library, starbase_libraries, X11_libraries
starbase_libraries, X11_libraries

Some drivers may require that additional libraries be linked with them.  For instance, using libddhpgl.a or libCADplt.a requires that libdvio.a be linked as well.  Also, some functions in the Starbase library require that the math library be linked in.  Functions that require the math library are view_camera, ellipse, arc, intarc, intcircle, inttext2d, text, intline_width, line_width, dccircle, and the shading functions.  See the Starbase Device Drivers Manual for specific requirements. 

For example, to compile and link the C program test.c with archive libraries for running on a terminal, hpgcrx, or hpgl plotter, use (the actual path name of the directory given in angle brackets below depends on the file system structure; see the Graphics Administration Guide for details):

 cc test.c -I <sb-include> -L <common>/lib -L <x11r5>
-lddhpterm -lddgcrx -lddhpgl -lXwindow -lhpgfx1 -lhpgfx2 -lXhp11 -lX11 -lXext -ldvio -lm -o test -O
-lhpgfx2 -lXhp11 -lX11 -lXext -ldvio -lm -o test -O
 

Note that -lhpgfx1 must precede -lhpgfx2. 

To compile and link the C program test.c with shared libraries for running on a terminal, hpgcrx, or hpgl plotter, use:

 cc test.c -I <sb-include> -L <common>/lib -L <x11r5>
-lXwindow -lhpgfx -lXhp11 -lX11 -ldvio -lm -ldld -o test -O
-lhpgfx -lXhp11 -lX11 -ldvio -lm -ldld -o test -O

LINKING STARBASE PROGRAMS TO RUN IN

THE X WINDOW SYSTEM

To load a Starbase program that may be directed to an X11 window, you need to include the X11 window libraries, and possibly the byte driver.  The byte driver needs to be included for programs that draw to obscured graphics windows that have backing store.  Again, the order is important:

 driver(s), [byte_driver], window_library location, window_library, starbase_libraries, X11_libraries
starbase_libraries, X11_libraries

For example, to compile with archive libraries (the actual path name of the directory given in angle brackets below depends on the file system structure; see the Graphics Administration Guide for details):

 
cc test.c -I <sb-include> -L <common>/lib -L <x11r5> -lddgcrx -lddbyte -lXwindow -lhpgfx1 -lhpgfx2 -lXhp11 -lX11 -lXext -lm -o test -lXext -lm -o test

To compile with shared libraries:

 
cc test.c -II <sb-include> -L <common>/lib -L <x11r5> -lXwindow -lhpgfx
-lXhp11 -lX11 -lm -ldld -o test -lhpgfx -lXhp11 -lX11 -lm -ldld -o test

HEADER FILES

The following templates show how to include Starbase header files with the various language bindings (the actual path names of the italicized bracketed directories in the following sections depend on the file system structure; see the Graphics Administration Guide for details):

C include Template

#include <starbase.c.h>
func()
{
/* function body */
}

main()
{
/* program body */
}

FORTRAN include Template

include ’<sb-include>/starbase.f1.h’
program main
CPARAMETER statements
character NULL
parameter(NULL = char(0))
include ’<sb-include>/starbase.f2.h’

CVARIABLE declarations

Cprogram body and/or subroutines and functions
end

Pascal include Template

program main(input, output);

$include ’<sb-include>/starbase.p1.h’$

{ CONSTANTS }
{ TYPES }
{ VARIABLES }

$include ’<sb-include>/starbase.p2.h’$

{ PROCEDURES AND FUNCTIONS }

begin
{program body}
end.

FILES

The following files make up the Starbase Graphics Library.  Each is shown with a description of its function. These archive libraries are located in the <common>/lib directory (the actual path names of the directories in angle brackets in this section depend on the file system structure; see the Graphics Administration Guide for details). 

   libhpgfx1.amain library for Starbase
  libhpgfx2.astub entry points for Starbase
  libXwindow.aX Windows support library (for Starbase)
  libXwindow.aX Windows support library (for Starbase)

  Also device drivers of the form libdd*.a

These shared libraries are located in <common>/lib:

   libhpgfx.slmain library for Starbase
  libXwindow.slX Windows support library (for Starbase)
  libXwindow.slX Windows support library (for Starbase)

  Also device drivers of the form libdd*.sl

The following header files are found in the <sb-include> directory.  Include the appropriate header file based on the programming language used in the source file. 

   starbase.c.hC program header file
  starbase.f1.hFORTRAN77 program header file
  starbase.f2.hFORTRAN77 program header file
  starbase.p1.hPascal program header file
  starbase.p2.hPascal program header file
  starbase.p2.hPascal program header file

The files residing in the <common>/daemons directory with the form sb_daemon_*.* are the Starbase input daemons.  The *.* is the version number of the daemon. 

The Starbase stroke font files reside in <sb-font>/* where * is the type of font used. 

The error catalog files reside in <nls>/hpgfx.cat. 

The file /etc/opt/starbase/defaults contains information about what fonts are loaded during a gopen, and what the character switching mode is after a gopen. Entries in this file may be modified, and will affect all gopens done on the workstation.  The comments in the file describe what text or font attribute is affected.  The following default files contain information about what fonts are loaded during a gopen, and what the character switching mode is after gopen.

$SB_DEFAULTS The defaults file specified by $SB_DEFAULTS is for application-specific font information. 

.sb_defaults The file .sb_defaults residing in user’s directory is for user-specific font information. 

/etc/opt/starbase/defaults
The file /etc/opt/starbase/defaults is for system default.  These defaults files are accessed in the order:

$SB_DEFAULTS, $HOME/.sb_defaults, /etc/opt/starbase/defaults.  The structure of the defaults file is described in defaultsfile(4).

SIGNALS

It is not recommended to use Starbase calls within a signal handler.  There is state information within a procedure that can be modified or lost if a second Starbase procedure is called while the first procedure is processing that information.  If it is necessary to use Starbase calls, keep track of the current active Starbase file descriptor, and use a different file descriptor to the same device.  Make sure this second file descriptor is not used outside the signal handler.  To reset the device, at the end of the signal handler make a call to the current active device using a Starbase procedure that does not actually access the device, such as inquire_color_table with a count of 0. 

If a Starbase program is expecting several signals, the following considerations are recommended to avoid conflicts with Starbase system calls.  The signals can simply be blocked using sigblock.  If receipt of signals is necessary, the sc_syscall_action parameter of the scp structure should be set to SIG_RESTART (as described in sigvector(2) and signal(5) of HP-UX Reference).  By doing so, the kernel is informed to restart the system call after the interrupt is handled.  This does not guarantee the system call will be completed, however taking the precautionary step will increase the probability of success. 
 

COORDINATE SYSTEMS

There are five Starbase coordinate systems: Modelling Coordinates (MCs), World Coordinates (WCs), floating point Virtual Device Coordinates (VDCs), integer Virtual Device Coordinates (VDCs), and integer Device Coordinates (DCs).  Floating point operations are either 2-D or 3-D, and provide functions for light sources, shading, and hidden surface removal.  Floating point operations are available by default, or by using the FLOAT_XFORM gopen mode.  Integer operations provide only 2-D transformations, and are available only when using the INT_XFORM gopen mode.  When using INT_XFORM mode, floating point operations are not available.  Device coordinate operations are always available.  Although the majority of Starbase procedures are used with only one coordinate system, a few of them are used with two, and some with all three.  A list of Starbase procedures and which system they are used with appears below. 
 

Floating point only:

Integer only:

Device coordinate only:

Common to Floating point and Integer:

Common to all systems:

SEE ALSO

Starbase Reference.  Starbase Graphics Techniques.  Starbase Device Drivers Manual.  HP-UX Reference: cc(1), f77(1), ld(1), pc(1). 
 

Hewlett-Packard Company  —  November 03, 1994