NAME

dl_control − control optional display list functionality

SYNOPSIS

C Syntax:

void dl_control(fildes, funcode, arg1, arg2);
int fildes, funcode;
dl_control_arg *arg1, *arg2;

FORTRAN77 Syntax:

subroutine dl_control(fildes, funcode, arg1, arg2)
integer*4 fildes, funcode
integer*4 arg1(64), arg2(64)
or
real arg1(64), arg2(64)
or
character arg1(255), arg2(255)

Pascal Syntax:

procedure dl_control(fildes,funcode:integer;
var arg1,arg2:dl_control_arg);

DESCRIPTION

Input Parameters

fildes Integer file descriptor returned by gopen when an I/O path to a graphic device is opened. 

funcode Function to be performed by this routine: SET_MEMORY_ALLOC_SIZES, INQ_MEMORY_ALLOC_SIZES, SET_PK_SPEED, INQ_PK_SPEED, SET_PK_STACK, INQ_PK_STACK. 

Input/Output Parameters

arg1 and arg2 Pointers to argument lists. 

Discussion

This (optional) function provides additional application control over the operation of the display list. 

The argument lists pointed to by arg1 and arg2 can contain additional information for the operation or be used to return results of the operation.  In C, dl_control_arg is defined in <sbdl.c.h> as:

typedef union {
inti[64];
floatf[64];
charc[255];
} dl_control_arg;

In Pascal, dl_control_arg is defined in <sbdl.p1.h> as:

dl_control_arg = record
case integer of
     0: (i : array[1..64] of integer);
     1: (f : array[1..64] of real);
     2: (c : array[1..255] of char);
end;

The function codes, funcode, are described as follows:

 
SET_MEMORY_ALLOC_SIZES − set the default memory size settings. 

This function code is used to specify the memory size (in bytes) initially reserved for a display list, and for any subsequent memory block allocations for a display list. 

The arg1 parameter specifies the allocation sizes:

arg1.i[0]
specifies the initial size (in bytes) of
memory to be reserved for a display list.

arg1.i[1]
specifies the size (in bytes) of subsequent
memory allocations for a display list.

The arg2 parameter is ignored. 

arg1.i[1] specifies the size of any subsequent memory allocations that may be reserved after the initial allocation is consumed.  The minimum size for an allocation is 1024 bytes. If an allocation  value less than 1024 bytes is specified, dl_control() will ignore it and use 1024.  The maximum value will be limited by the operating system. The default value for both arg1 and arg2 is 262144 bytes (1/4MB). 

If dl_control() is called using this function code, the call should be executed before creating any segments unless the default size of 1/4MB is desired. If dl_control() has not been called with this function code prior to creating the first segment, the default initial size will be reserved for the display list. 

This function can be used at any time to modify the sizes of subsequent memory allocations, and is intended to allow applications to tailor the scratch memory size to their display list. For example, a small application might set the initial size to a value large enough to contain the entire display list, thereby eliminating future allocations and ensuring that the display list is not spread out in memory. Conversely, larger applications may utilize the function to dynamically tune the amount of memory allocated as the display list grows in size. 
 

Example:
     dl_control_arg arg1, arg2;
     arg1.i[0] = 1048576;
    arg1.i[1] = 2048;
     dl_control(fildes, SET_MEMORY_ALLOC_SIZES, &arg1, &arg2);
 

INQ_MEMORY_ALLOC_SIZES − inquire the scratch memory size settings. 

The arg2 parameter returns the allocation sizes:

arg2.i[0]
specifies the initial size (in bytes) of
memory to be reserved for a display list.

arg2.i[1]
specifies the size (in bytes) of additional
allocations for a display list.

The arg1 parameter is ignored. 
 

SET_PK_SPEED − control use of batched picking (hardware dependent). 

arg1.i[0]
specifies the number of primitives that
may be batched together, when used on a
device with batched picking capability.
Higher values allow more primitives to be
batched together and inquired once during
picking (up to the device’s maximum).
Zero indicates that batched picking is
disabled.

The arg2 parameter is ignored. 

Note that if batched picking is used, the PK_STOP pick control flag (see set_pick_mode(3G)) is not guaranteed to stop traversal exactly with the picked element; it may stop up to arg1.i[0] primitives later. 

The PK_SPEED value is reset every time pick mode is changed via set_pick_mode.  Thus, applications which override the default settings must explicitly set PK_SPEED for each pick mode change. 
 

Example:
     dl_control_arg arg1, arg2;
     arg1.i[0] = 220;
     dl_control(fildes, SET_PK_SPEED, &arg1, &arg2);
 

INQ_PK_SPEED − inquire batched picking setting. 

arg2.i[0]
returns the realized batched picking setting.
The realized value may be less than the requested
value depending on the batched picking capability
of the device.

The arg1 parameter is ignored. 
 

SET_PK_STACK − control software use of batched picking. 

The arg1 parameter sets the size of the software pick stack, used in conjunction with batched picking:

arg1.i[0]
specifies the size of the software pick stack.

The arg2 parameter is ignored. 

This setting has no effect if batched picking is not used.  The pick stack is used to manage segment traversal as well as the batched pick pipeline.  For optimum performance, its value should be equal to the maximum number of possible batched primitives (as per the SET_PK_SPEED value), plus one for every label (see dl_label(3G)) encountered during the traversal of a batch of primitives, plus two for every segment reference (see call_segment(3G), execute_segment(3G), cond_call_segment(3G), and cond_execute_segment(3G)) encountered during the traversal of a batch of primitives. Larger pick stacks do not hinder performance, but do consume additional memory. The size of the pick stack cannot be set to zero; any attempt to do so will be silently ignored.

Example:
     dl_control_arg arg1, arg2;
     arg1.i[0] = 64;
     dl_control(fildes, SET_PK_STACK, &arg1, &arg2);
 

INQ_PK_STACK − inquire the size of the software pick stack. 

arg2.i[0]
returns the size of the software pick stack.

The arg1 parameter is ignored. 
 

ERRORS

1 Graphics device not initialized for this operation. 

6 Improper parameter value. 

20 Parameter value is out of range. 

SEE ALSO

pick_from_segment(3G), set_pick_mode(3G). 

Hewlett-Packard Company  —  HP-UX Release 9.0: August 1992