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. 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) 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), 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 )
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 )
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 )
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 )
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_extentdraw2d* marker_type
* add_names_to_setdraw3dmove2d

append_text	* drawing_mode	move3d
arc	execute_segment	partial_ellipse
await_retrace	file_to_bitmap	partial_polygon2d* backface_controlfile_to_dcbitmappartial_polygon3d * background_colorfile_to_intbitmap* pattern_define * background_color_index* fill_color* perimeter_color * bank_switch* fill_color_index* perimeter_color_index * bezier_knots* fill_dither* perimeter_repeat_length * bf_controlflush_buffer* perimeter_type * bf_fill_colorflush_matricespolygon2d * bf_fill_color_indexgescapepolygon3d * bf_interior_style* hatch_orientationpolyline2d * bf_perimeter_color* hatch_spacingpolyline3d * bf_perimeter_color_index* hatch_typepolymarker2d * bf_perimeter_repeat_length° hidden_surfacepolymarker3d * bf_perimeter_typehighlight_attributespop_matrix * bf_surface_coefficients* highlight_color_indexpop_state * bf_surface_modelhighlight_onpush_matrix2d
bitmap_print	* highlight_type	push_matrix3d
bitmap_to_file	intarc	push_state
block_move	intbitmap_print	push_vdc_matrix
block_write	intbitmap_to_file	quadrilateral_mesh
buffer_mode	intblock_move	rectangle
call_segment	intblock_write	* remove_all_names_from_set* character_expansion_factor* intcharacter_height* remove_names_from_set * character_height* intcharacter_widthreplace_matrix2d * character_slantintcirclereplace_matrix3d * character_width* intclip_rectangle* set_cull_size * character_width_factorintconcat_transform2dset_disp_traversal_control * clear_controlintdraw2dset_extent
clear_view_surface	* interior_style	* set_extent_displacements* clip_depth* inthatch_spacingset_p1_p2 * clip_indicator* intline_repeat_length† set_pick_traversal_control * clip_rectangle* intline_widthshade_mode
concat_transformation2d	intmove2d	shade_range
concat_transformation3d	intpartial_arc	spline_curve2d
cond_call_segment	intpartial_circle	spline_curve3d
cond_execute_segment	intpartial_polygon2d	spline_surface
cond_return	* intperimeter_repeat_length	* surface_coefficients* curve_resolutionintpolygon2d* surface_model
dbuffer_switch	intpolyline2d	text2d
dcbitmap_print	intpush_matrix2d	text3d
dcbitmap_to_file	* intra_character_space	* text_alignment
dcblock_move	intrectangle	* text_color
dcblock_write	intreplace_matrix2d	* text_color_index* dccharacter_heightinttext2d* text_font_index * dccharacter_width* inttext_orientation2d* text_line_path
dccircle	* intvdc_extent	* text_line_space
dcdraw	intview_matrix2d	* text_orientation2d* dcmarker_size* intview_port* text_orientation3d
dcmove	intview_window	* text_path
dcpartial_polygon	* light_ambient	* text_precision
dcpolygon	* light_attenuation	* text_switching_mode
dcpolyline	* light_model	triangular_strip
dcpolymarker	* light_source	* u_knot_vector
dcrectangle	* light_switch	* v_knot_vector
dctext	* line_color	* vdc_extent* default_knots* line_color_index* vdc_justification
define_color_table	* line_endpoint	* vertex_format
define_trimming_curve	* line_repeat_length	view_camera* depth_cue* line_typeview_matrix2d * depth_cue_color* line_widthview_matrix3d * depth_cue_color_indexmake_picture_currentview_port * depth_cue_range* mapping_modeview_volume * depth_indicator* marker_colorview_window * designate_character_set* marker_color_indexviewpoint * display_enable* marker_orientation* write_enable † dl_label* marker_size° zbuffer_switch
double_buffer

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 /usr/lib.

libdddl.a Display List Device Driver

libsbdl.a Starbase Display List Subsystem Library

libsbdlrefs.a 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 /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 in the link sequence, but precede the Starbase device-independent libraries libsb1.a and libsb2.a. Programs that require the auxiliary library libsbdlrefs.a should follow the link instructions given in interpret_ele(3G). 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>
main()
{
/* main program body */
}
graphics_application_function()
{
/* function body */
}

FORTRAN77 Include Template:

INCLUDE ’/usr/include/starbase.f1.h’
INCLUDE ’/usr/include/sbdl.f1.h’
PROGRAM main
C
CApplication PARAMETER statements - constant definitions
C
CHARACTER NULL
PARAMETER( NULL = CHAR(0) )
INCLUDE ’/usr/include/starbase.f2.h’
INCLUDE ’/usr/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 ’/usr/include/starbase.f2.h’
INCLUDE ’/usr/include/sbdl.f2.h’
C
CRest of application subroutine.
C
END

Pascal Include Template:

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

Museum

Related Articles