inquire_capabilities(3G)

NAME

inquire_capabilities − return capabilities of gopened device

SYNOPSIS

C Syntax:

int inquire_capabilities ( fildes, size, flags );
int fildes, size;
char *flags;

FORTRAN77 Syntax:

integer*4 function inquire_capabilities ( fildes, size, flags )
integer*4 fildes
integer*4 size
byte flags ( size )

Pascal Syntax:

type gbyte=0..255;
function inquire_capabilities ( fildes, size:integer;
flags:packed array[1..SIZE_OF_CAPABILITIES] of gbyte ):integer;

DESCRIPTION

Input Parameters

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

size The size, in bytes, of memory allocated for flags

Output Parameters

flags Address of memory allocated for flags

Discussion

inquire_capabilities can be used to determine the capabilities of the gopened graphics device (determined by fildes).

The flags parameter is byte oriented. Each byte should be referenced by definitions in the Starbase include files. Within each byte are logical flags represented by one bit each. The value of each flag should be accessed by a logical ’anding’ of the byte with the definition for the flag found in the Starbase include files. The values are guaranteed to be zero unless specifically set by inquire_capabilities. The flags parameter has the following definitions:

HLHSR_CAPABILITIES
IC_ZBUFFER_16(16-bit Z-buffer supported)
IC_ZBUFFER_24(24-bit Z-buffer supported)
FACING_CAPABILITIES
IC_FACE_CULLING(back-face cull supported)
IC_BACKFACE_ATTRS(back-face attributes)
COLOR_1_CAPABILITIES
IC_GRAY_SCALE or IC_GREY_SCALE(grayscale dev)
IC_CMAP_NORMAL(indexed color supported)
IC_CMAP_MONOTONIC(cmap_monotonic supported)
IC_CMAP_FULL(direct color supported)
IC_DITHERING(dithering supported)
IC_GAMMA_RENDERING(gamma corrected rendering)
IC_GAMMA_CMAP(gamma correction in color map)
IC_OVERLAY_TRANSPARENT(transparent color present)
COLOR_2_CAPABILITIES
IC_MULTIPLE_CMAPS(multiple hardware color maps present)
LIGHTING_CAPABILITIES
IC_LIGHTING(lighting supported)
IC_LIGHTS_8(only 8 lights supported)
IC_LIGHTS_16(16 lights supported)
SHADING_CAPABILITIES
IC_SHADING(smooth shading supported)
IC_DEPTH_CUEING(depth cueing supported)
TRANSPARENCY_CAPABILITIES
IC_ALPHA_TRANSPARENCY(alpha transparency)
IC_SCREEN_DOOR(screen door transparency)
MODEL_CLIP_CAPABILITIES
IC_MODEL_CLIP(model clipping supported)
IC_MODEL_CAP(model capping supported)
IC_MODEL_INTERFERENCE(interference checking)
WITH_DATA_CAPABILITIES
IC_ILLUM_BITS(illumination bits)
IC_ALPHA_BLEND(alpha blending supported)
IC_CONTOURING(contouring supported)
IC_DEFORMATION(deformation supported)
IC_TEXTURE_MAP(texture mapping supported)
PRIMITIVES_1_CAPABILITIES
IC_AA_VECTORS(anti-aliased vectors)
IC_AA_POLYGONS(anti-aliased polygons)
IC_NURBS_4(4th order NURBS supported)
IC_NURBS_6(6th order NURBS supported)
IC_NURBS_TRIM(trimming curves supported)
IC_FA_FM(Fast Alpha / Font Manager)
PRIMITIVES_2_CAPABILITIES(RESERVED FOR FUTURE)
CONTROL_CAPABILITIES
IC_BACKING_STORE(backing store supported)
IC_PER_WINDOW_DBUFFER(per-window double-buffer control)
IC_TRANS_WIN_IMAGE_CURSOR(Starbase Cursors should be rendered
using an image plane fildes with
Transparent Overlay Windows. If
this bit is not set, an overlay plane
fildes should be used.)
PERF_HINTS_1_CAPABILITIES
IC_HW_ZBUFFER(means only 1 z resolution)
IC_CONVEXITY(convexity hint used)
PERF_HINTS_2_CAPABILITIES(RESERVED FOR FUTURE)

The application allocates the memory and passes the size, in bytes, allocated to inquire_capabilities.

The definition fills SIZE_OF_CAPABILITIES (defined in include files) bytes of data. flags may be extended in the future beyond SIZE_OF_CAPABILITIES bytes although effort was made to leave room for extension within the space already given. inquire_capabilities will fill out the information to the size of the memory specified, but not go beyond that.

The indicated support for the different color map modes and for anti-aliasing do take into consideration the visual type (depth and visual class — refer to the "Using Starbase with the X Window System" chapter in Starbase Graphics Techniques for further information on visual types).

Some capabilities, such as lighting, shading, and anti-aliasing, are supported only in certain modes (for example, CMAP_FULL ). Support will be indicated if possible to set a required mode even though the device may not currently be in one of the required mode(s).

Some capabilities (for example, gamma correction) indicate support for the corresponding gescape (for example, GAMMA_CORRECTION)

Return Value

A non-zero value is returned if the size specified was not large enough to hold all the information. There are no other error conditions except an invalid fildes, where an error is generated and the return value is undefined.

A non-zero value returned is the actual size needed to fit all the information. Since the application must make source level changes in order to take advantage of any extended information in future releases, it is not really necessary to check for a return value except when determining the data of interest to the application.

Examples

C Language:
/* ... */
#include <starbase.c.h>
int fields, rtnval;
char flags[SIZE_OF_CAPABILITIES];
/* fildes = gopen(for example, your device w/NULL ptr for driver);*/
rtnval = inquire_capabilities(fields, SIZE_OF_CAPABILITIES, flags);
/* process data using defines in include files */
if (!(flags[LIGHTING_CAPABILITIES] & IC_LIGHTING))
printf("warning -- lighting is not supported");
if (!(flags[SHADING_CAPABILITIES] & IC_SHADING))
printf("warning -- shading is not supported");
/* ... */
FORTRAN77 Language:
C ...
include ’starbase.f1.h’
include ’starbase.f2.h’
integer*4 fields, rtnval
byte flags(SIZE_OF_CAPABILITIES)
C fildes = gopen(for example, your device w/NULL ptr for driver);
rtnval = inquire_capabilities(fields, SIZE_OF_CAPABILITIES, flags)
rtnval = ZEXT(flags(LIGHTING_CAPABILITIES))
if (BTEST(rtnval, IC_LIGHTING))
cPRINT*,’warning -- lighting is not supported’
rtnval = ZEXT(flags(LIGHTING_SHADING))
if (BTEST(rtnval, IC_SHADING))
cPRINT*,’warning -- shading is not supported’
C ...
Pascal Language:
{ ... }
$include ’starbase.p1.h’$
fields, size, rtnval : integer;
flags : packed array[1..SIZE_OF_CAPABILITIES] of gbyte;
$include ’starbase.p2.h’$
{ fildes := gopen(for example, your device w/NULL ptr for driver);*}
size := SIZE_OF_CAPABILITIES;
rtnval := inquire_capabilities(fields, size, flags);
if (((flags[LIGHTING_CAPABILITIES] div IC_LIGHTING) mod 2) <> 0) then
writeln( ’warning -- lighting is not supported’ );
if (((flags[SHADING_CAPABILITIES] div IC_SHADING) mod 2) <> 0) then
writeln( ’warning -- shading is not supported’ );
{ ... }

Museum