gopen(3G)

NAME

gopen − open I/O path to, create environment for, and initialize graphics device

SYNOPSIS

C Syntax:

int gopen ( path, kind, driver, mode );
char *path, *driver;
int kind, mode;

FORTRAN77 Syntax:

integer*4 function gopen ( path, kind, driver, mode )
character*(*) path, driver
integer*4 kind, mode

Pascal Syntax:

function gopen ( path:string255; kind:integer;
driver:string255; mode:integer ):integer;

DESCRIPTION

Input Parameters

path Device file name for the device to be opened. This file is usually found in the <screen> directory (the actual path name of the directory given in angle brackets depends on the file system structure; see the Graphics Administration Guide for details).

kind One of the constants:

INDEV Device is to be used for input only.

OUTDEV Device is to be used for output only.

OUTINDEV Device is to be used for both input and output.

driver One of the following:

Character String Character representation of the hardware device type. See the Starbase Device Drivers Manual for details.

NULL Use a device driver based upon the path, kind, and the mode parameter.

mode Word containing flags used at open to specify control. The following flags can be bitwise ORed together:

SPOOLED Output is spooled to a file. Do not inquire from the device. If this bit is set, the path parameter should name a regular file or FIFO special file.

RESET_DEVICE Device is completely initialized, including color map initialization and clearing the view surface.

INIT Device is initialized in a device-dependent manner.

THREE_D All transformations are three dimensional, including point, line, and polygon transformations as well as matrix concatenations.

MODEL_XFORM As part of the opening, the device is prepared for shading of output primitives and/or removal of back-facing polygons. This means that output primitives must be transformed in two stages:

1. All output primitives are transformed by the top matrix on the matrix stack (if any exist on the stack). This transforms the primitives from modeling coordinates to world coordinates. At this stage rendering calculations can be made.

2. Primitives are transformed from world coordinates to device coordinates by the current viewing and device transformations. If the device is not opened in this mode, all transformations can be concatenated and performed simultaneously.

INT_XFORM Only integer and common operations will be performed. All floating point operations will cause an error.

INT_XFORM_32 Only integer and common operations will be performed. All Floating point operations will cause an error. This mode is provided for compatibility of integer precision with previous devices. INT_XFORM will use a faster transformation pipeline with slightly less precision. It is recommended that you use INT_XFORM unless maximum precision is required. If maximum precision is required, even at the expense of performance, use INT_XFORM_32.

FLOAT_XFORM Only Floating point and common operations will be performed. All integer operations will cause an error.

ACCELERATED Use the accelerated device driver if possible. This flag only has meaning when the driver parameter is NULL.

UNACCELERATED Use the unaccelerated device driver if possible. This flag only has meaning when the driver parameter is NULL.

Discussion

This function returns a non-negative integer upon a successful device opening. This integer is called the file descriptor and is referred to by the name fildes in this manual. The file descriptor remains open across exec system calls. See fcntl(2). However, state descriptor information is not preserved across exec system calls.

If the SPOOLED bit is set, Starbase will open the file named by the path argument; this action may overwrite an existing file.

By default, no process can have more than _NFILE file descriptors open simultaneously. _NFILE is an HP-UX system variable that defines the number of open files allowed per process at any given time. The value of _NFILE is found in the header file /usr/include/stdio.h. If file descriptors in the range [0,_NFILE-1] are already in use, gopen() will fail even if the number of simultaneously open file descriptors allowed has been increased beyond the default limit. Note that the first gopen() to a device may use several file descriptors for establishing connections to other pertinent processes.

When a graphics device is opened, many defaults are set. Some are specified in the file /etc/opt/starbase/defaults.

Integer operations are only available when using the INT_XFORM or INT_XFORM_32 gopen mode. When in INT_XFORM or INT_XFORM_32 mode Floating point operations are not available for that fildes. Floating point operations are available by the default, or can be specified with FLOAT_XFORM mode. For a list of Integer operations, floating point operations and common operations see the starbase(3G) manual page.

If the driver parameter is NULL, gopen() will make a call to inquire_device_driver() to determine which device driver to use. The mode parameter is passed to inquire_device_driver(). See inquire_device_driver(3G) for more information on how a device driver is selected.

RETURN VALUE

Upon successful completion, a non-negative integer called the file descriptor (fildes) is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error.

EXAMPLES

The following example opens the window associated with the device file for output, <screen>/window (the actual path name of the directory given in angle brackets depends on the file system structure; see the Graphics Administration Guide for details), and performs the device initialization. This example is valid for raster devices only.

fildes = gopen("<screen>/window", OUTDEV, NULL, INIT|THREE_D|MODEL_XFORM);

For non-raster devices the device driver must be specified. For example, the following gopen statement is valid for a cgm device:

fildes = gopen("cgm.file", OUTDEV, "hpcgm", INIT);

DEFAULTS

By default all transform operations are floating point.

Museum

Related Articles