SET DEPTH CUE REPRESENTATION(3P+) — Kubota Pacfic Computer Inc. (29 February 1991)

NAME

SET DEPTH CUE REPRESENTATION − define a depth cue representation entry in the workstation table of defined depth cue representations

SYNOPSIS

C Syntax

void
pset_dcue_rep ( ws, index, rep )
Pintws;workstation identifier
Pintindex;depth cue bundle index
Pdcue_bundle∗rep;depth cue representation pointer

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

SET DEPTH CUE REPRESENTATION assigns parameter values defining a depth cue operation to a specified index number in the workstation table of defined depth cue representations. Each entry in this table contains a value for depth cue mode, reference planes, scaling, and colour. When enabled, depth cueing is applied to all output primitives subsequently displayed.

Depth cueing mixes a scaled portion of the depth cue colour with the primitive colour as a function of the z coordinate in NPC space. Using the background colour as the depth cue colour, this operation allows you to fade the colour of the parts of the primitives that are further from the viewer in the display.

C Input Parameters

wsThe workstation identifier specifies the workstation for which the depth cue representation is to be defined. The workstation must have been opened with the OPEN WORKSTATION subroutine before calling SET DEPTH CUE REPRESENTATION.

indexThe index to the workstation depth cue bundle table.

The index number corresponds to an entry in the table of defined depth cue operations in the workstation state list. Up to 20 depth cue table entries can be defined. Entry zero is predefined to a depth cue mode of PSUPPRESSED and cannot be changed. Entries other than zero can be changed with the SET DEPTH CUE REPRESENTATION subroutine.

repA pointer to a Pdcue_bundle data structure containing attribute values defining a depth cue representation. A Pdcue_bundle structure is defined in phigs.h as follows:

typedef struct {
Pdcue_modemode;/∗ depth cue mode ∗/
Pfloatref_planes[2];/∗ depth cue reference planes ∗/
Pfloatscaling[2];/∗ depth cue scaling ∗/
Pgcolrcolr;/∗ depth cue colour ∗/
} Pdcue_bundle;

Pdcue_mode is defined as:

typedef enum {
PSUPPRESSED,
PALLOWED
} Pdcue_mode;

Refplanes and scaling entries of 0 are back reference plane and corresponding scaling factors. Refplanes 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 {
Pinttype;/∗ indirect, RGB, CIE, HSV, HLS ∗/
union {
     Pintind;/∗ index in workstation colour bundle table ∗/
     struct {
          Pfloatx;/∗ red, hue, etc. ∗/
          Pfloaty;/∗ green, saturation, lightness, etc. ∗/
          Pfloatz;/∗ blue, value, saturation, etc. ∗/
     } general;
} val;
} Pgcolr;

Constants defined for colour type are:

0       PINDIRECTIndirect
1       PMODEL_RGBRed, Green, Blue
2       PMODEL_CIELUVCIE
3       PMODEL_HSVHue, Saturation, Value
4       PMODEL_HLSHue, Lightness, Saturation

Execution

When a SET DEPTH CUE REPRESENTATION is called, the entry index in the table of defined depth cue representations on the workstation identifier is set to the values in rep.

During structure traversal, the current depth cue representation is selected from the workstation table by a structure element created by the SET DEPTH CUE INDEX subroutine. While the depth cue mode of the current representation is ALLOWED, the depth cue operation defined by the other representation parameters is applied to all the following primitives in the structure network.

The depth cueing operation changes the primitive colours in the display as a function of their z coordinate in NPC space. The first number in scaling specifies the portion of the primitive colour that is combined with the depth cue colour at, or in front of, the front reference plane. The second scaling value specifies the portion of primitive colour applied at, or behind, the back reference plane. The portion of depth cue colour applied to primitives between the two planes is scaled by a value linearly interpolated between the two scaling values.

When a workstation is opened, entries zero and one are initialized with the following representation:

Entry 0Entry 1
depth cue modeSUPPRESSED ALLOWED
depth cue reference planes0.0, 1.00.0, 1.0
depth cue scaling1.0, 1.0 0.0, 1.0
depth cue colour(INDIRECT, 0) (INDIRECT, 0)

For depth cue reference planes and depth cue scaling, the first value is the back reference plane and scaling.

ERRORS

003Ignoring function, function requires state (PHOP, WSOP, ∗, ∗)

054Ignoring function, the specified workstation is not open

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

103Ignoring function, setting this bundle table entry would exceed the maximum number of entries allowed in the workstation bundle table

110Ignoring function, the specified colour model is not available on the workstation

603Ignoring function, the depth cue index is less than zero

616Ignoring function, invalid reference planes; DQMIN > DQMAX

Museum