NAME

INQUIRE DEPTH CUE REPRESENTATION - inquire for depth cue representation for specified workstation

SYNOPSIS

C Syntax

void

pinq_dcue_rep ( ws, index, type, error_ind, rep )

Pint             ws;           workstation identifier
Pint             index;        polyline index
Pinq_type        type;         type of returned value
Pint             * error_ind;  OUT error indicator
Pdcue_bundle     * rep;        OUT depth cue representation

FORTRAN Syntax

SUBROUTINE pqdcr ( WKID, IDEPTH, ITYPE, ERRIND, MODE, BPLANE, FPLANE, BSCALE, FSCALE, COLMOD, IDCOLR, DCOLR )

INTEGER      WKID                  workstation identifier
INTEGER      IDEPTH                depth cue index
INTEGER      ITYPE                 inquiry type (PSET, PREALI )
INTEGER      ERRIND                OUT error indicator
INTEGER      MODE                  OUT depth cue mode
REAL         BPLANE, FPLANE        OUT back and front depth planes
REAL         BSCALE, FSCALE        OUT back and front scale values
INTEGER      COLMOD                OUT colour model
INTEGER      IDCOLR                OUT indirect depth cue colour
REAL         DCOLR(3)              OUT array of depth cue colour

Required PHIGS Operating States

(PHOP,WSOP, * ,* )

DESCRIPTION

Purpose

INQUIRE DEPTH CUE REPRESENTATION returns the attribute values of a specified entry in the workstation table of depth cue representations. For a full description of the contents of the bundle table entry and a description of the depth cue representation table, see SET DEPTH CUE REPRESENTATION .

This is a SunPHIGS Extension function based on PHIGS PLUS and is not part of the PHIGS standard.

C Input Parameters

ws

The workstation identifier.

index

The depth cue index.

type

An enumerated value specifying whether the values to be returned are those originally specified by the application (PINQ_SET), or are those resulting after PHIGS mapped them to ones available on the workstation (PINQ_REALIZED). A Pinq_type structure is defined as:

typedef enum {

PINQ_SET,

PINQ_REALIZED

} Pinq_type;

C Output Parameters

error_ind

A pointer to the location to store the error number of any error detected by this function.

rep

A pointer to a Pdcue_bundle data structure containing attribute values defining a depth cue representation. A Pdcue_bundle structure is defined as:

typedef struct {

Pdcue_mode     mode;           /* depth cue mode * /
Pfloat          ref_planes[2];  /* depth cue reference planes * /
Pfloat          scaling[2];     /* depth cue scaling * /
Pgcolr         colr;           /* depth cue colour * /

} Pdcue_bundle;

Pdcue_mode is defined as:

typedef enum {

PSUPPRESSED,

PALLOWED

} Pdcue_mode;

ref_planes and scaling entries of 0 are back reference plane and corresponding scaling factors. ref_planes and scaling entries of 1 are front reference plane and corresponding scaling factors. These scaling factors define the portion of the primitive colour that should be combined with the depth cue colour, as a function of z in NPC.

Pgcolr is defined as:

typedef struct {

Pint

type;

/* indirect, RGB, CIE, HSV, HLS * /

union {

Pint

ind;

/* index in workstation colour

bundle table * /

struct {

             Pfloat       x;      /* red, hue, and so on * /
             Pfloat       y;      /* green, saturation, lightness,
                                     and so on * /
             Pfloat       z;      /* blue, value, saturation, and so on * /
          } general;
        } val;
} Pgcolr;

FORTRAN Input Parameters

All of the following data types are predefined in phigs77.h.

WKID

The identifier of the workstation for which the depth cue representation is being inquired.

IDEPTH

The depth cue index into the workstation depth cue table.

ITYPE

An enumerated value specifying whether the values to be returned are those originally specified by the application (Set), or those resulting after PHIGS mapped them to ones available on the workstation (Realized). Valid values are:

0   PSET      Set
1   PREALI    Realized

FORTRAN Output Parameters

ERRIND

The error number of any error detected by this function.

MODE

The depth cue MODE controls depth cue disabling or enabling. The depth cue mode contains one of the following values:

0   PSUPPR     Disable Depth Cueing
1   PALLOW     Enable Depth Cueing

BPLANE,FPLANE

The back and front depth planes, z values in NPC. BPLANE is the back depth plane, which defines a back reference plane for depth cueing. FPLANE is the front depth plane, which defines a front reference plane for depth cueing.

BSCALE,FSCALE

The back and front scale values. BSCALE is the back scale value, between 0.0 and 1.0, that corresponds to the z value of the back reference plane. FSCALE is a front scale value, between 0.0 and 1.0, that corresponds to the z value of the front depth cue reference plane. These values define the portion of the primitive colour that should be combined with the depth cue colour as a function of z in NPC.

COLMOD

COLMOD is the colour model that determines the type of colour to be used. If this value is PINDIR or zero, then IDCOLR will contain an indexed colour value. If COLMOD is greater than zero, then DCOLR will contain the depth cue colour. The valid values for COLMOD are:

0   PINDIR   Colour Index Specified
1   PRGB     Red, Green, and Blue
2   PCIE     CIE Colour Model
3   PHSV     Hue, Saturation, and Value
4   PHLS     Hue, Lightness, and Saturation

IDCOLR

IDCOLR is an index into the workstation colour table. This integer value determines the depth cue colour. This value is not used if COLMOD is greater than

zero.

DCOLR(3)

DCOLR(3) is an array of reals containing the depth cue colour. This array is not used when COLMOD is equal to zero. The reals are stored as:

DCOLR(1) = Red, Hue, and so on

DCOLR(2) = Green, Saturation, Lightness, and so on

DCOLR(3) = Blue, Value, Saturation, and so on

Execution

If the inquired information is available, the error indicator is returned as zero and values are returned in the output parameters.

If the specified depth cue index is not present in the depth cue table on the workstation and the specified type of returned value is Realized, the representation for the depth cue index zero is returned.

If the inquired information is not available, then the values returned in the output parameters are undefined, and the error indicator is set to one of the following error numbers to indicate the reason for nonavailability.

Since this is an inquiry function, ERROR HANDLING is not invoked when an error is detected by this function.

ERRORS

003

Ignoring function, function requires state (PHOP, WSOP, * ,* )

054

Ignoring function, specified workstation is not open

059

Ignoring function, specified workstation does not have output capability (that is, the workstation category is not OUTPUT, OUTIN, or MO)

101

Ignoring function, specified representation has not been defined

119

Ignoring function, depth cue index is less than zero

SEE ALSO

SET DEPTH CUE REPRESENTATION (3PP)

SET DEPTH CUE INDEX (3PP)

INQUIRE LIST OF DEPTH CUE INDICES (3PP)

INQUIRE PREDEFINED DEPTH CUE REPRESENTATION (3PP)