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. Each segment is an ordered list of elements corresponding 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. The special Starbase device driver, libdddl.a, 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) or execute_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), set_invisibility_filter(3G), seg_control(3G), and ele_control(3G) provide means of controlling which portions of a segment network will be displayed during display traversal. Set_disp_traversal_control(3G) generates segment elements that can cause a return from the current segment during traversal or a return from the entire segment network. Set_invisibility_filter(3G) gives finer control by allowing individual portions of a segment network (identified by add_names_to_set(3G), remove_names_from_set(3G), and remove_all_names_from_set(3G) elements) to be passed over during traversal. Seg_control(3G) allows entire segments to be passed over during traversal. Ele_control(3G) provides the finest control possible, by allowing individual elements to be passed over during traversal. Seg_control(3G) can also cause individual segments to be highlighted during traversal.

Traversal can also be controlled through cond_call_segment(3G), cond_execute_segment(3G) and cond_return(3G). These functions conditionally traverse parts of the display list according to condition index values set by set_extent(3G). These values are set by examining the placement and size of an extent box relative to the current clip limits. This information is also used by adapt_clip_to_extent(3G) to selectively disable clip planes during traversal, thereby improving performance.

Inheritance of attributes can be controlled through push_state(3G), pop_state(3G), execute_segment(3G), and cond_execute_segment. Push_state(3G) and pop_state(3G) push and pop a subset of the current attribute state onto and off of a stack, respectively. Execute_segment(3G) and cond_execute_segment(3G) perform like their counterparts call_segment(3G) and cond_call_segment(3G) except that the same subset of the current attribute state is saved when traversal of the segment begins, and restored when traversal of the segment ends. This provides a powerful tool for the control of attributes.

Segment contents can be manipulated by the 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 an element. Copy_segment(3G) copies an entire segment into the open segment.

A special element, element 0, 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, printing the contents of segments, and archiving and retrieving segments. Delete_segment(3G) deletes an entire segment, delete_all_segments(3G) deletes an entire segment network, 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. Print_element(3G) prints to standard output a description of the current element. Inq_ele(3G) and interpret_ele(3G) extract and replace the current element from a user-supplied data structure. Inq_content(3G) extracts the current element into a well-defined data structure for perusal or editing.

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 the Starbase functions 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 potentially many primitives falling within the pick aperture will be accepted. Pick traversal is controlled in the same manner as display traversal, by using set_pick_traversal_control(3G), set_pick_filter(3G), seg_control(3G), dl_control(3G), and ele_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.

adapt_clip_to_extent( fildes, enable )
add_names_to_set( fildes, count, names )
application_data( fildes, count, data )
call_segment( fildes, segno )
change_segment_references( fildes, old_segno, new_segno )
close_segment( fildes )
cond_call_segment( fildes, cond_index_select, comp_flag, segno )
cond_execute_segment( fildes, cond_index_select, comp_flag, segno )
cond_return( fildes, cond_index_select, comp_flag )
copy_segment( fildes, segno )
delete_all_segments( fildes )
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 )
dl_control( fildes, funcode, arg1, arg2)
ele_control( fildes, control, on )
execute_segment( fildes, segno )
inq_application_data( fildes, data )
inq_application_data_size( fildes, size )
inq_called_segno( fildes, segno )
inq_calling_segment_count( fildes, segno, seg_count )
inq_calling_segment_list( fildes, segno, seg_list )
inq_cond_index( fildes, cond_index_select, value )
inq_content( fildes, type_array, count_array, int_array, float_array, char_array )
inq_content_sizes( fildes, num_params, num_ints, num_floats, num_chars )
num_chars )
inq_ele( fildes, ele )
inq_ele_control( fildes, control )
inq_ele_ptr( fildes, offset )
inq_ele_ptr_at_bound( fildes, at_top, at_bot )
inq_ele_size( fildes, size )
inq_ele_type( fildes, ele_type )
inq_extent_info( fildes, dc_extent, clip_mask, diagonal_len )
inq_highlighting_filter( fildes, i_names, x_names )
inq_highlighting_filter_sizes( fildes, i_count, x_count )
inq_invisibility_filter( fildes, i_names, x_names )
inq_invisibility_filter_sizes( fildes, i_count, x_count )
inq_nameset( fildes, names )
inq_nameset_size( fildes, size )
inq_num_refs( fildes, segno, count )
inq_open_segment( fildes, segno, seg_open )
inq_open_segment_and_mode( fildes, segno, seg_open, display )
inq_pick_filter( fildes, i_names, x_names )
inq_pick_filter_sizes( fildes, i_count, x_count )
inq_pick_path( fildes, path )
inq_pick_path_depth( fildes, depth )
inq_seg_control( fildes, segno, control )
inq_segment_count( fildes, count )
inq_segment_exists( fildes, segno, exists )
inq_segment_list( fildes, list )
inq_traversal_depth( fildes, depth )
interpret_ele( fildes, ele )
open_segment( fildes, segno, append, display )
pick_from_segment( fildes, segno, found )
pop_state( fildes )
print_element( fildes, abbreviate_arrays )
push_state( fildes )
refresh_element( fildes )
refresh_segment( fildes, segno )
refresh_segment_hsr( fildes, segno )
remove_all_names_from_set( fildes )
remove_names_from_set( fildes, count, names )
rename_segment( fildes, old_segno, new_segno )
rename_segment_and_references( fildes, old_segno, new_segno )
replace_ele( fildes )
seg_control( fildes, segno, control, on )
set_cull_size( fildes, cull_size )
set_disp_traversal_control( fildes, control )
set_ele_ptr( fildes, offset )
set_ele_ptr_at_end( fildes )
set_ele_ptr_relative( fildes, offset )
set_ele_ptr_relative_to_label( fildes, label_id, offset )
set_extent( fildes, mc_extent )
set_extent_displacements( fildes, vdc_displacements, dc_displacements )}
dc_displacements )
set_highlighting_filter( fildes, i_count, i_names, x_count, x_names )
set_invisibility_filter( fildes, i_count, i_names, x_count, x_names )
set_pick_filter( fildes, i_count, i_names, x_count, x_names )
set_pick_mode( fildes, check_hit )
set_pick_sense( fildes, sense )
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. Functions marked with * affect state that can be saved and restored with push_state(3G) and pop_state(3G) operations. Functions marked with † are always ignored during display traversals, and those marked with ° are always ignored during pick traversals (see ele_control(3G)).

* adapt_clip_to_extentdraw2dpartial_polygon2d
* add_names_to_setdraw3dpartial_polygon3d
* alpha_transparency* drawing_modepartial_polygon_with_data3d

append_text	ellipse	* pattern_define†° application_dataexecute_segment* perimeter_color
arc	file_to_bitmap	* perimeter_color_index
await_retrace	file_to_dcbitmap	* perimeter_filter* backface_controlfile_to_intbitmap* perimeter_repeat_length * background_color* fill_color* perimeter_type * background_color_index* fill_color_indexpolygon2d * bank_switch* fill_ditherpolygon3d * bezier_knotsflush_bufferpolygon_with_data3d * bf_alpha_transparencyflush_matricespolyhedron_with_data * bf_controlgescapepolyline2d * bf_fill_color* hatch_orientationpolyline3d * bf_fill_color_index* hatch_spacingpolyline_with_data3d * bf_interior_style* hatch_typepolymarker2d * bf_perimeter_color° hidden_surfacepolymarker3d * bf_perimeter_color_index* highlight_colorpolymarker_with_data3d * bf_perimeter_repeat_length* highlight_color_indexpolyrectangle * bf_perimeter_typehighlight_onpop_matrix * bf_surface_coefficients* highlight_typepop_state * bf_surface_modelintarcpush_matrix2d * bf_texture_indexintbitmap_printpush_matrix3d
bitmap_print	intbitmap_to_file	push_state
bitmap_to_file	intblock_move	push_vdc_matrix
block_move	intblock_write	quadrilateral_mesh
block_write	* intcharacter_height	quadrilateral_mesh_with_data
buffer_mode	* intcharacter_width	rectangle
call_segment	intcircle	* remove_all_names_from_set* character_expansion_factor* intclip_rectangle* remove_names_from_set * character_heightintconcat_transform2dreplace_matrix2d * character_slantintdraw2dreplace_matrix3d * character_width* interior_styleset_capping_planes * character_width_factor* inthatch_spacing* set_cull_size * clear_control* intline_repeat_lengthset_disp_traversal_control
clear_view_surface	* intline_width	set_extent* clip_depth* intmarker_size* set_extent_displacements * clip_indicatorintmove2d* set_model_clip_indicator * clip_rectangleintpartial_arc* set_model_clip_volume
concat_transformation2d	intpartial_circle	set_p1_p2
concat_transformation3d	intpartial_polygon2d	† set_pick_traversal_control
cond_call_segment	* intperimeter_repeat_length	shade_mode
cond_execute_segment	intpolycircle	shade_range
cond_return	intpolygon2d	spline_curve* contour_enableintpolyline2dspline_surface * curve_resolutionintpolymarker2d* surface_coefficients
dbuffer_switch	intpolyrectangle	* surface_model
dcbitmap_print	intpush_matrix2d	text2d
dcbitmap_to_file	* intra_character_space	text3d
dcblock_move	intrectangle	* text_alignment
dcblock_write	intreplace_matrix2d	* text_color* dccharacter_heightinttext2d* text_color_index * dccharacter_width* inttext_orientation2d* text_font_index
dccircle	* intvdc_extent	* text_line_path
dcdraw	intview_matrix2d	* text_line_space* dcmarker_size* intview_port* text_orientation2d
dcmove	intview_window	* text_orientation3d
dcpartial_polygon	* light_ambient	* text_path
dcpolycircle	* light_attenuation	* text_precision
dcpolygon	* light_model	* text_switching_mode
dcpolyline	* light_source	* texture_index
dcpolymarker	* light_switch	* texture_viewport
dcpolyrectangle	* line_color	* texture_window
dcrectangle	* line_color_index	triangular_strip
dctext	* line_endpoint	triangular_strip_with_data* default_knots* line_filter* u_knot_vector
define_color_table	* line_repeat_length	* v_knot_vector
define_contour_table	* line_type	* vdc_extent
define_texture	* line_width	* vdc_justification
define_trimming_curve	make_picture_current	* vertex_format* deformation_mode* mapping_modeview_camera * depth_cue* marker_colorview_matrix2d * depth_cue_color* marker_color_indexview_matrix3d * depth_cue_color_index* marker_orientationview_port * depth_cue_range* marker_sizeview_volume * depth_indicator* marker_typeview_window * designate_character_setmove2dviewpoint * display_enablemove3d* write_enable † dl_labelpartial_arc° zbuffer_switch
double_buffer	partial_ellipse

FILES

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

libdddl.a libdddl.sl Display List Device Driver

libsbdl.a libsbdl.sl Starbase Display List Subsystem Library

libsbdlrefs.a libsbdlrefs.sl Starbase Display List Subsystem Auxiliary Library

The auxiliary library libsbdlrefs.a is used to force the code for all functions in the list above to be loaded. This may be necessary with programs that use interpret_ele(3G).

The following files are found in directory <sb-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 <starbase>/examples/dl contains example programs presented in the Starbase Display List Programmer’s Manual, along with a makefile for compiling and linking these programs.

The directory <starbase>/demos/dl 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 or libsbdl.sl must follow application modules, driver libraries, and libwindow.a in the link sequence, but precede the Starbase device-independent libraries libsb1.a and libsb2.a or libsb.sl. Programs that require the auxiliary library libsbdlrefs.a or libsbdlrefs.sl should follow the link instructions given in interpret_ele(3G). For archive libraries, 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 using archive libraries for running on a terminal, hpgcrx, or hpgl plotter, use (the actual path names of the directories given in angle brackets in this section depend on the file system structure; see the Graphics Administration Guide for details):

cc test.c -I <sb-include> -L <sb-lib> -L <x11r5> -lddhpterm -lddgcrx -lhpgl -lsbdl -lsb1 -lsb2 -ldvio -lXhp11 -lX11 -lXext -o test -O

For shared libraries use:

cc test.c -I <sb-include> -L <sb-lib> -L <x11r5> -lhpgl -lsbdl -lsb -ldvio -lXhp11 -lX11 -ldld

INCLUDE FILE USAGE

The following templates show how include files should be used with the various language bindings (the actual path names of the directories given in angle brackets in this section depend on the file system structure; see the Graphics Administration Guide for details):

C Include Template:

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

FORTRAN77 Include Template:

INCLUDE ’<sb-include>/starbase.f1.h’
INCLUDE ’<sb-include>/sbdl.f1.h’
PROGRAM main
C
CApplication PARAMETER statements - constant definitions
C
CHARACTER NULL
PARAMETER( NULL = CHAR(0) )
INCLUDE ’<sb-include>/starbase.f2.h’
INCLUDE ’<sb-include>/sbdl.f2.h’
C
CRest of application main program.
C
END
SUBROUTINE graphics_application_subroutine
C
CApplication Subroutine PARAMETER statements - constant definitions
C
CHARACTER NULL
PARAMETER( NULL = CHAR(0) )
INCLUDE ’<sb-include>/starbase.f2.h’
INCLUDE ’<sb-include>/sbdl.f2.h’
C
CRest of application subroutine.
C
END

Pascal Include Template:

PROGRAM main( INPUT, OUTPUT );
     $INCLUDE ’<sb-include>/starbase.p1.h’$
    $INCLUDE ’<sb-include>/sbdl.p1.h’$
     { CONSTANT definitions }
    { TYPE definitions }
    { VARIABLE declarations }
     $INCLUDE ’<sb-include>/starbase.p2.h’$
    $INCLUDE ’<sb-include>/sbdl.p2.h’$
     { PROCEDURE and FUNCTION definitions }
BEGIN
    { main program body }
END.

Museum

Related Articles