SBDL(3G)

NAME

SBDL − Starbase Graphics Display List Subsystem Library description

DESCRIPTION

The Starbase Graphics Display List Subsystem Library provides procedures for use in managing hierarchical and dynamic display lists of Starbase functions. These library routines can be used in C, Pascal and FORTRAN77 programs.

Each Starbase device accessed with a gopen(3G) call has a corresponding display list associated with it. The display list is composed of a set of segments where each segment is an ordered list of elements, and each element corresponds to a Starbase or Starbase Display List Library function. Segment name is an integer used to identify a particular segment in a display list.

Elements are added to the open segment when a Starbase or Starbase Display List procedure is invoked. Open_segment(3G) is used to name a segment as the open segment. It is also used to create a new segment or to open an existing segment for additions or modification. Close_segment(3G) closes the segment.

To display segments on a corresponding output device, use display_segment(3G) and refresh_segment(3G). Use display_element(3G) and refresh_element(3G) to display individual elements on an output device. A special Starbase device driver is provided for building display lists without associating the list with a particular graphics device. Gopen(3G) opens the unassociated display_list device as a device-independent display list.

A segment can also be made to call or reference another segment by using call_segment(3G). Since referenced segments can also reference other segments, a linked structure of segments can be built. A segment plus all the segments it references directly or indirectly is called a segment network. When a segment containing calls is displayed, the entire segment network is also displayed. Several procedures are provided for making inquiries that are related to segments and the structure of a specified segment network. They include inq_segment_count/list/exists(3G), inq_open_segment(3G), inq_calling_segment(3G), and inq_num_refs(3G).

Traversal is the process of stepping through a segment network for display. Traversal depth is a counter used to monitor the nesting depth of segment calls during traversal. Starting with an initial value of zero, it is incremented each time a segment call is processed and decremented each time the end of a segment is encountered. Set_traversal_depth(3G) can be used to impose a limit on the number of nested segment calls that will be traversed. Inq_traversal_depth(3G) returns the current value of this limit. Set_disp_traversal_control(3G) provides a means for controlling which portions of a segment network will be traversed. This procedure generates segment elements that can cause an immediate return from the current segment during traversal or an immediate return from the entire segment network.

Segment contents can be manipulated by use of editing commands. Associated with each segment is an element pointer which points to an element referred to as the current element. Whenever a new element is added to a segment, the new element is inserted after the current element and becomes the new current element. Use set_ele_ptr(3G) to move the element pointer to a different element. Use inq_ele_ptr(3G) to determine the position of the current element and inq_ele_type(3G) to determine the current element type. Delete_eles(3G) deletes elements from a segment and replace_ele(3G) replaces them. Copy_segment(3G) copies an entire segment into the open segment.

A special element, element0, is located at the start of each segment so that the element pointer can be positioned before the first real element. Element 0 is used only as a pointer, and cannot be deleted.

Other procedures are provided for modifying segment names and segment network structure. Delete_segment(3G) deletes an entire segment, rename_segment(3G) changes the name associated with a segment, and change_segment_references(3G) is used to modify the structure of a segment network.

A segment network can be searched for elements that fall within a specified volume. This operation is called a pick and is done with pick_from_segment(3G). This procedure traverses a specified segment network, searching for hits on elements. A hit on an element occurs when the element would generate a visible image that intersects the pick aperture (see set_pick_window(3G) and set_pick_depth(3G)). Inq_pick_path(3G) returns the path to the picked primitive. Since many primitives may fall within the pick aperture, many primitives may be hit. Set_pick_mode(3G) is used to set the pick mode and thus determine which of the many primitives that may fall within the pick aperture will be accepted. Pick traversal can be controlled in the same manner as display traversal by using set_pick_traversal_control(3G).

Display list labels are elements that can be added to segments for the purpose of setting the element pointer and providing additional identification for picked primitives. Dl_label(3G) inserts a display list label into the open segment. See set_ele_ptr(3G) for an explanation of how to use labels for editing and inquire_pick_path(3G) for details of their use in picking.

A program can also insert and retrieve its own data as an element in the open segment. See application_data(3G) and inq_application_data(3G) for details.

The following procedures are provided in the Starbase Display List Subsystem.

application_data( fildes, size, data )
call_segment( fildes, segno )
change_segment_references( fildes, old_segno, new_segno )
close_segment( fildes )
copy_segment( fildes, segno )
delete_eles( fildes, count )
delete_segment( fildes, segno )
delete_segment_and_references( fildes, segno )
display_element( fildes, devdes )
display_segment( fildes, segno, devdes )
display_segment_hsr( fildes, segno, devdes )
dl_label( fildes, label_id )
inq_application_data( fildes, data )
inq_application_data_size( fildes, size )
inq_calling_segment_count( fildes, segno, seg_count )
inq_calling_segment_list( fildes, segno, seg_list )
inq_ele_ptr( fildes, offset )
inq_ele_ptr_at_bound( fildes, at_top, at_bot )
inq_ele_type( fildes, ele_type )
inq_num_refs( fildes, segno, count )
inq_open_segment( fildes, segno, seg_open )
inq_pick_path( fildes, path )
inq_pick_path_depth( fildes, depth )
inq_segment_count( fildes, count )
inq_segment_list( fildes, list )
inq_segment_exists( fildes, segno, exists )
inq_traversal_depth( fildes, depth )
open_segment( fildes, segno, append, display )
pick_from_segment( fildes, segno, found )
refresh_element( devdes )
refresh_segment( devdes, segno )
refresh_segment_hsr( devdes, segno )
rename_segment( fildes, old_segno, new_segno )
rename_segment_and_references( fildes, old_segno, new_segno )
replace_ele( fildes )
set_disp_traversal_control( fildes, control )
set_ele_ptr( fildes, offset )
set_ele_ptr_relative( fildes, offset )
set_ele_ptr_relative_to_label( fildes, label, offset )
set_ele_ptr_at_end( fildes )
set_pick_mode( fildes, check_hit )
set_pick_traversal_control( fildes, control )
set_traversal_depth( fildes, depth )
traversal_lock(fildes,lock)

The following subset of Starbase functions can be stored in a display list. Any other Starbase functions invoked while a segment is open will not be stored in the display list and will function as if the segment were not open.

append_text	dl_label	pop_matrix
application_data	double_buffer	print_bitmap
arc	draw2d	print_dcbitmap
await_retrace	draw3d	push_matrix2d
backface_control	drawing_mode	push_matrix3d
background_color	ellipse	push_vdc_matrix
background_color_index	file_to_bitmap	rectangle
bank_switch	file_to_dcbitmap	replace_matrix2d
bitmap_to_file	fill_color	replace_matrix3d
block_move	fill_color_index	set_disp_traversal_control
block_write	fill_dither	set_p1_p2
buffer_mode	flush_matrices	set_pick_traversal_control
call_segment	gescape	shade_mode
character_expansion_factor	hidden_surface	shade_range
character_height	interior_style	spline_curve
character_slant	intra_character_space	spline_surface
character_width	light_ambient	surface_model
clear_control	light_model	text2d
clear_view_surface	light_source	text3d
clip_depth	light_switch	text_alignment
clip_indicator	line_color	text_color
clip_rectangle	line_color_index	text_color_index
concat_transformation2d	line_repeat_length	text_font_index
concat_transformation3d	line_type	text_line_path
curve_resolution	make_picture_current	text_line_space
dbuffer_switch	mapping_mode	text_orientation2d
dcbitmap_to_file	marker_color	text_orientation3d
dcblock_move	marker_color_index	text_path
dcblock_write	marker_orientation	text_precision
dccharacter_height	marker_size	text_switching_mode
dccharacter_width	marker_type	u_knot_vector
dcdraw	move2d	u_spline_basis
dcmarker_size	move3d	v_knot_vector
dcmove	partial_arc	v_spline_basis
dcpartial_polygon	partial_ellipse	vdc_extent
dcpolygon	partial_polygon2d	vertex_format
dcpolyline	partial_polygon3d	view_camera
dcpolymarker	perimeter_color	view_matrix2d
dcrectangle	perimeter_color_index	view_matrix3d
dctext	perimeter_repeat_length	view_port
default_knots	perimeter_type	view_volume
pdefine_color_table	olygon2d	view_window
define_trimming_curve	polygon3d	viewpoint
depth_cue	polyline2d	viewport_justification
depth_indicator	polyline3d	write_enable
designate_character_set	polymarker2d	zbuffer_switch
display_enable	polymarker3d

FILES

The following files make up the Starbase Graphics Display List Subystem Library. Each is shown with a description of its function. These files are located in directory /usr/lib.

libdddl.a Display List Device Driver

libsbdl.a Starbase Display List Subsystem Library

The following files are found in directory /usr/include and should be used with the corresponding programming language.

sbdl.c.h C program header file

sbdl.f1.h FORTRAN77 program header file

sbdl.f2.h FORTRAN77 program header file

sbdl.p1.h Pascal program header file

sbdl.p2.h Pascal program header file

The directory /usr/lib/sbdl/examples contains example programs presented in the Starbase Display List Programmer’s Manual, along with a makefile for compiling and linking these programs.

The directory /usr/lib/sbdl/demos contains demonstration programs and a makefile to compile and link them.

LOADING STARBASE DISPLAY LIST SUBSYSTEM PROGRAMS

In addition to the appropriate Starbase libraries the Starbase Display List Subsystem libraries must also be loaded. The order of specification of link files is extremely important. The Starbase Display List Subsystem library, libsbdl.a must follow application modules, driver libraries, and libwindow.a, but precede the Starbase device-independent libraries in the link sequence. If the display list device is used the device driver for it, libdddl.a should be linked with the rest of the Starbase device driver libraries.

For example: to compile and link the C program test.c for running on a terminal, hp98700 or hpgl plotter, use:

cc test.c -lddhpterm -ldd98700 -lhpgl -lsbdl -lsb1 -lsb2 -ldvio -o test -O

INCLUDE FILE USAGE

The following templates show how include files should be used with the various language bindings:

C Include Template:

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

FORTRAN77 Include Template:

include ’/usr/include/starbase.f1.h’
include ’/usr/include/sbdl.f1.h’
program main
CPARAMETER statements
character NULL
parameter(NULL = char(0))
include ’/usr/include/starbase.f2.h’
include ’/usr/include/sbdl.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’$
$include ’/usr/include/sbdl.p1.h’$
{ CONSTANTS }
{ TYPES }
{ VARIABLES }
$include ’/usr/include/starbase.p2.h’$
$include ’/usr/include/sbdl.p2.h’$
{ PROCEDURES AND FUNCTIONS }
begin
{program body}
end.

Museum

Related Articles