starbase(3G)
NAME
starbase − Starbase Graphics Library description
DESCRIPTION
The Starbase Graphics Library consists of procedures used to generate graphics pictures and text. This library is based on the emerging ANSI standard known as Virtual Device — Computer Graphics Interface (ANSI VD-CGI).
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. In addition to the standard ANSI CGI functions, Starbase provides asynchronous input functions, 3-dimensional transformations, and access to many device-dependent hardware features.
LINKING STARBASE PROGRAMS
It is extremely important that link files be specified in the following order:
driver(s),
libsb1.a,
libsb2.a .
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 for running on a terminal, hp98720 or hpgl plotter, use:
cc test.c -lddhpterm -ldd98720 -lhpgl -lsb1 -lsb2 -ldvio -lm -o test -O
LINKING STARBASE PROGRAMS TO RUN IN
THE HP WINDOWS/9000 ENVIRONMENT
Series 300 only
To load a Starbase program that may be directed to a window, the window library and possibly the byte driver must be included. The byte driver needs to be included for programs that draw to obscured graphics windows which are retained. Again, the order is important:
driver(s), [byte_driver], window_library, libsb1.a, libsb2.a
For example:
cc test.c -ldd98720 -lddbyte -lwindow -lsb1 -lsb2 -lm -o test -O
For some monochrome devices, the bit driver is an alternative to the byte driver. This is because the bit driver requires one eighth the memory for a single-plane retained raster.
LINKING STARBASE PROGRAMS TO RUN IN
THE X WINDOW SYSTEM
To load a Starbase program that may be directed to an X.11 window, you need to include the X.11 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, libsb1.a, libsb2.a, libXhp11.a, libX11.a
For example:
cc test.c -ldd98720 -lddbyte -L /usr/lib/X11R5 -lXwindow -lsb1 -lsb2 -lXhp11 -lX11 -lm test -o
For some monochrome devices, the bit driver is used instead of the byte driver because the bit driver requires one-eighth the memory for a single-plane retained raster.
HEADER FILES
The following templates show how to include Starbase header files with the various language bindings:
C include Template
#include <starbase.c.h>
func()
{
/* function body */
}
main()
{
/* program body */
}
FORTRAN include Template
include ’/usr/include/starbase.f1.h’
program main
CPARAMETER statements
character NULL
parameter(NULL = char(0))
include ’/usr/include/starbase.f2.h’
CVARIABLE declarations
Cprogram body and/or subroutines and functions
end
Pascal include Template
program main(input,output);
$include ’/usr/include/starbase.p1.h’$
{ CONSTANTS }
{ TYPES }
{ VARIABLES }
$include ’/usr/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 files are located in the /usr/lib directory.
libsb1.amain library for Starbase
libsb2.astub entry points for Starbase
(For series 300 only.)
libddbit.aHP9000/Windows and X.11 retained raster driver (bit/pixel)
libddbyte.aHP9000/Windows and X.11 retained raster driver (byte/pixel)
libwindow.aHP9000/Windows library
libXwindow.aX Windows support library (for Starbase)
Also device drivers of the form libdd*.a
The following header files are found in the /usr/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
The files residing in the /usr/lib/starbase directory with the form sb_daemon_*.* are the Starbase input daemons. The *.* is the version number of the daemon.
The files residing in the /usr/lib/starbase/hp* directory (where * is the hardware type) named te_mcode are the micro code for Starbase. Those in the same directories named te_data are the micro code data files.
The Starbase stroke font files reside in /usr/lib/starbase/stroke/* where * is the type of font used.
The error catalog files reside in either /usr/lib/nls/C/n-computer/sb.cat (pre-7.0 release) or in /usr/lib/nls/C/sb.cat (7.0 release and after).
The file /usr/lib/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 effect all gopens done on the workstation. The comments in the file describe what text or font attribute is affected. The following defaultfiles contain information about what fonts are loaded during a gopen, and what the character 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.
/usr/lib/starbase/defaults
The file /usr/lib/starbase/defaults is for system default. These defaults files are accessed in the order: $SB_DEFAULTS,$HOME/.sb_defaults,/user/lib/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)). By doing so, the kernel is informed to restart the system call after the interrupt is handled. This does not gaurantee the system call will be completed, however taking the precautionry step will increase the probability of success.
COORDINATE SYSTEMS
There are three Starbase coordinate systems: floating point Virtual Device Coordinates (VDC), integer Virtual Device Coordinates (VDC), and integer Device Coordinates (DC). 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:
| alpha_transparency | polyhedron_with_data |
| append_text | polyline2d |
| arc | polyline3d |
| backface_control | polyline_with_data3d |
| bf_alpha_transparency | polymarker2d |
| bitmap_print | polymarker3d |
| bitmap_to_file | polymarker_with_data3d |
| block_move | pop_matrix2d |
| block_read | pop_matrix3d |
| block_write | push_matrix2d |
| character_height | push_matrix3d |
| character_width | quadrilateral_mesh |
| clip_depth | quadrilateral_mesh_with_data |
| clip_depth | quadrilateral_mesh_with_data |
| clip_rectangle | read_locator_event |
| concat_matrix | rectangle |
| concat_transformation3d | replace_matrix3d |
| contour_enable | request_locator |
| dc_to_vdc | sample_locator |
| default_knots | set_capping_planes |
| define_contour_table | set_locator |
| define_texture | set_model_clip_indicator |
| define_trimming_curve | set_model_clip_volume |
| deformation_mode | set_pick_depth |
| depth_cue | set_pick_window |
| depth_indicator | shade_mode |
| draw2d | shade_range |
| draw3d | spline_curve2d |
| echo_type | spline_curve3d |
| echo_update | spline_surface |
| ellipse | surface_model |
| file_to_bitmap | text2d |
| hatch_spacing | text3d |
| hidden_surface | text_alignment |
| inq_pick_depth | text_line_path |
| inq_pick_window | text_line_space |
| inquire_current_position2d | text_orientation2d |
| inquire_current_position3d | text_orientation3d |
| inquire_text_extent | texture_viewport |
| light_ambient | texture_window |
| light_model | transform_point |
| light_source | transform_points |
| light_switch | triangular_strip |
| line_filter | triangular_strip_with_data |
| line_repeat_length | u_knot_vector |
| marker_orientation | v_knot_vector |
| marker_size | vdc_extent |
| move2d | vdc_to_dc |
| move3d | vdc_to_wc |
| partial_arc | vertex_format |
| partial_ellipse | view_camara |
| partial_polygon2d | view_matrix2d |
| partial_polygon3d | view_matrix3d |
| partial_polygon_with_data3d | view_port |
| perimeter_filter | view_volume |
| perimeter_repeat_length | view_window |
| polygon2d | viewpoint |
| polygon3d | wc_to_vdc |
| polygon_with_data3d | zbuffer_switch |
Integer only:
| file_to_intbitmap | intpartial_circle |
| intarc | intpartial_polygon2d |
| intbitmap_print | intperimeter_repeat_length |
| intbitmap_to_file | intpolygon2d |
| intblock_move | intpolyline2d |
| intblock_read | intpolycircle |
| intblock_write | intpolyrectangle |
| intcharacter_height | intpop_matrix2d |
| intcharacter_width | intpush_matrix2d |
| intcircle | intread_locator_event2d |
| intclip_rectangle | intrectangle |
| intconcat_matrix2d | intreplace_matrix2d |
| intconcat_transform2d | intrequest_locator2d |
| intdraw2d | intsample_locator2d |
| intecho_type2d | intset_locator2d |
| intecho_update2d | intset_pick_window |
| inthatch_spacing | inttext2d |
| intinquire_current_position2d | inttext_orientation2d |
| intinquire_pick_window | inttransform_point2d |
| intinquire_text_extent2d | intvdc_extent |
| intline_repeat_length | intview_matrix2d |
| intline_width | intview_port |
| intmove2d | intview_window |
| intpartial_arc |
Device coordinate only:
| dcbitmap_print | dcmarker_size |
| dcbitmap_to_file | dcmove |
| dcblock_move | dcpartial_polygon |
| dcblock_read | dcpolycircle |
| dcblock_write | dcpolygon |
| dccharacter_height | dcpolyline |
| dccharacter_width | dcpolymarker |
| dccircle | dcpolyrectangle |
| dcdraw | dcrectangle |
| dcecho_type | dctext |
| dcecho_update | file_to_dcbitmap |
Common to Floating point and Integer:
| character_expansion_factor | pop_matrix |
| character_slant | push_vdc_matrix |
| clip_indicator | set_hit_mode |
| curve_resolution | set_p1_p2 |
| flush_matrices | text_path |
| inquire_hit | text_precision |
| intra_character_space | vdc_justification |
| mapping_mode |
Common to all systems:
| await_event | inquire_display_mode |
| await_retrace | inquire_fb_configuration |
| background_color | inquire_gerror |
| background_color_index | inquire_id |
| bank_switch | inquire_input_capabilities |
| buffer_mode | inquire_request_status |
| clear_control | inquire_sizes |
| clear_view_surface | interior_style |
| dbuffer_switch | line_color |
| define_color_table | line_color_index |
| define_raster_echo | line_type |
| designate_character_set | make_picture_current |
| disable_events | make_X11_gopen_string |
| display_enable | marker_color |
| double_buffer | marker_color_index |
| drawing_mode | marker_type |
| enable_events | pattern_define |
| file_print | perimeter_color |
| fill_color | perimeter_color_index |
| fill_color_index | perimeter_type |
| fill_dither | read_choice_event |
| flush_buffer | request_choice |
| gclose | rendering_hints |
| gerr_message | rgb_to_index |
| gerr_print_control | sample_choice |
| gerr_procedure | set_signals |
| gescape | text_color |
| gopen | text_color_index |
| hatch_orientation | text_font_index |
| hatch_type | text_switching_mode |
| initiate_request | track |
| inquire_capabilities | track_off |
| inquire_color_table | write_enable |
DEVICE SPECIAL FILES
HPGL, CADplt, and CADplt2 device drivers
The <Sc> parameter is the select code of the HP_IB or Serial Interface card. The <AD> parameter is the HP_IB address. The <LU> parameter is the logical unit of the HP_IB or Serial Interface card. The <Pt> parameter is the serial port address.
Series 300 Syntax
HP-IB: mknod /dev/hpgl c 21 0x<Sc><AD>00
Serial: mknod /dev/hpgls c 1 0x<Sc><Pt>04
Series 800 Syntax
HP-IB: mknod /dev/hpgl c 21 0x00<LU><AD>
Serial: mknod /dev/hpgls c 1 0x00<LU><Pt>
HP_HIL device driver
Series 300 Syntax
The <AD> parameter is the one digit address on the HIL serial loop.
mknod /dev/hil<AD> c 24 0x0000<AD>0
Series 700 Syntax
The <AD> parameter is the one digit address on the HIL serial loop.
mknod /dev/hil<AD> c 24 0x2030<AD>0
Series 800 Syntax
The <LU> parameter is the one digit hardware logical unit number. The <AD> parameter is the device’s one digit HIL serial loop address.
mknod /dev/hil<AD> c 24 0x000<LU><AD>0
or
mknod /dev/hil_<LU>.<AD> c 24 0x000<LU><AD>0
HPTERM device driver
Use device file /dev/tty if you want the output to go to the terminal you are logged in on. See your System Administrator for details on using other terminals. Other terminals are usually designated as /dev/tty01, /dev/tty02, etc.
HP300h/HP300l device driver
Series 300 Syntax
mknod /dev/crt c 12 0x000000 ... (when alone)
mknod /dev/crt c 12 0x000100 ... (when also using hp98204b)
Series 800 Syntax
This driver is not supported on the series 800.
HP9836A device driver
Series 300 Syntax
mknod /dev/crt c 12 0x000000
Series 800 Syntax
This driver is not supported on the series 800.
HP98550 device driver
Series 300 Syntax
For internal devices:
mknod /dev/crt c 12 0x000000 (for all planes)
mknod /dev/ocrt c 12 0x000001 (for overlay planes)
mknod /dev/icrt c 12 0x000002 (for image planes)
For external device, <Sc> is the external select code of the HP98548/49/50 devices.
mknod /dev/crt c 12 0x<Sc>0200 (for all planes)
mknod /dev/ocrt c 12 0x<Sc>0201 (for overlay planes)
mknod /dev/icrt c 12 0x<Sc>0202 (for image planes)
Series 800 Syntax
The <LU> parameter is the hardware logical unit number.
For internal devices:
mknod /dev/crt c 14 0x00<LU> (for all planes)
mknod /dev/ocrt c 14 0x00<LU>01 (for overlay planes)
mknod /dev/icrt c 14 0x00<LU>02 (for image planes)
HP98556 device driver
Series 300 Syntax
The <Sc> parameter is the external select code of the HP98556 device.
mknod /dev/crt c 12 0x<Sc>0200 (for all planes)
mknod /dev/ocrt c 12 0x<Sc>0201 (for overlay planes)
mknod /dev/icrt c 12 0x<Sc>0202 (for image planes)
Series 800 Syntax
The <LU> parameter is the logical unit number of the A1020A graphics subsystem.
mknod /dev/crt c 14 0x00<LU>00
mknod /dev/ocrt c 14 0x00<LU>01
mknod /dev/icrt c 14 0x00<LU>02
HP98700 device driver
Series 300 Syntax
The <Sc> parameter is the external select code of the HP98700 device.
mknod /dev/crt c 12 0x000000 ... (for console device)
mknod /dev/crt c 12 0x<Sc>0200 ... (for external select code)
Series 800 Syntax
This driver is not supported on the series 800.
HPEntry Level VRX device driver
Series 400 Syntax
mknod /dev/crt c 12 0x000300
This driver is only supported on the series 400.
HP98704/HP98705 device driver
Series 300 Syntax
The <Sc> parameter is the external select code of the HP98705 device.
mknod /dev/crt c 12 0x<Sc>0200 ... (for image planes)
mknod /dev/ocrt c 12 0x<Sc>0201 ... (for three overlay planes)
mknod /dev/o4crt c 12 0x<Sc>0203 ... (for four overlay planes)
Series 700 Syntax
The <Sl> parameter is the SGC slot number of the graphics interface card. On SPU’s with one graphics slot, this number is 1. On SPU’s with two graphics slots, it is 0 or 1.
mknod /dev/crt c 12 0x<Sl>00000 ... (for image planes)
mknod /dev/ocrt c 12 0x<Sl>00001 ... (for three overlay planes)
mknod /dev/o4crt c 12 0x<Sl>00003 ... (for four overlay planes)
Series 800 Syntax
This device is not supported on the series 800.
HP98710 device driver
Series 300 Syntax
The <Sc> parameter is the external select code of the HP98710 device.
mknod /dev/crt c 12 0x000000 ... (for console device)
mknod /dev/crt c 12 0x<Sc>0200 ... (for external select code)
Series 800 Syntax
This driver is not supported on the series 800.
HP98720 device driver
Series 300 Syntax
The <Sc> parameter is the external select code of the HP98720 device.
mknod /dev/crt c 12 0x000000 ... (for console device)
mknod /dev/crt c 12 0x<Sc>0200 ... (for external select code)
Series 800 Syntax
The <LU> parameter is the hardware logical unit number.
mknod /dev/crt c 14 0x00<LU>00
HP98720w device driver
Series 300 Syntax
The <Sc> parameter is the external select code of the HP98720w device.
mknod /dev/ocrt c 12 0x000001 ... (for console device)
mknod /dev/ocrt c 12 0x<Sc>0201 ... (for external select code)
Series 800 Syntax
The <LU> parameter is the hardware logical unit number.
mknod /dev/crt c 14 0x00<LU>00
HP98721 device driver
Series 300 Syntax
The <Sc> parameter is the external select code of the HP98721 device.
mknod /dev/crt c 12 0x000000 ... (for console device)
mknod /dev/crt c 12 0x<Sc>0200 ... (for external select code)
Series 800 Syntax
The <LU> is the hardware logical unit number.
mknod /dev/crt c 14 0x00<LU>00
HPA1659 device driver
Series 700 Syntax
The <Sl> parameter is the SGC slot number of the graphics interface card. On SPU’s with one graphics slot, this number is 1. On SPU’s with two graphics slots, it is 0 or 1.
mknod /dev/crt c 12 0x<Sl>00000 ... (for image planes)
HP98730 device driver
Series 300 Syntax
The <Sc> parameter is the external select code of the HP98730 device.
mknod /dev/crt c 12 0x000000 ... (for console device)
mknod /dev/crt c 12 0x<Sc>0200 ... (for external select code)
Series 800 Syntax
The <LU> parameter is the hardware logical unit number.
mknod /dev/crt c 14 0x00<LU>00
HP98731 device driver
Series 300 Syntax
The <Sc> parameter is the external select code of the HP98731 device.
mknod /dev/crt c 12 0x000000 ... (for console device)
mknod /dev/crt c 12 0x<Sc>0200 ... (for external select code)
Series 800 Syntax
The <LU> is the hardware logical unit number.
mknod /dev/crt c 14 0x00<LU>00
HP98735/HP98736 device driver
Series 300 Syntax
The <Sc> parameter is the external select code of the HP98735 device.
mknod /dev/crt c 12 0x<Sc>0200 ... (for image planes)
mknod /dev/ocrt c 12 0x<Sc>0201 ... (for three overlay planes)
mknod /dev/o4crt c 12 0x<Sc>0203 ... (for four overlay planes)
Series 700 Syntax
The <Sl> parameter is the SGC slot number of the graphics interface card. On SPU’s with one graphics slot, this number is 1. On SPU’s with two graphics slots, it is 0 or 1.
mknod /dev/crt c 12 0x<Sl>00000 ... (for image planes)
mknod /dev/ocrt c 12 0x<Sl>00001 ... (for three overlay planes)
mknod /dev/o4crt c 12 0x<Sl>00003 ... (for four overlay planes)
Series 800 Syntax
This device is not supported on the series 800.
HP Keyboard device driver
Locator Keyboard device driver
Use device file /dev/tty if you want the input to come from the terminal you are logged in on. See your System Administrator for details on using other terminals. Other terminals are usually designated as /dev/tty01, /dev/tty02, etc.
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 — HP-UX Release 9.0: August 1992