SET DEPTH CUE REPRESENTATION(3P+) — MISC. REFERENCE MANUAL PAGES

NAME

SET DEPTH CUE REPRESENTATION − creates a structure element containing the value depth cue representation

SYNOPSIS

C Syntax

void
psetdcuerep ( wsid, index, rep )
Pintwsid;workstation identifier
Pintindex;depth cue index number
Pdcuebundl∗rep;pointer to depth cue representation

FORTRAN Syntax

SUBROUTINE psdcr ( WKID, IDEPTH, MODE, BPLANE, FPLANE, BSCALE, FSCALE,
COLMOD, IDCOLR, DCOLR )
INTEGERWKIDworkstation identifier
INTEGERIDEPTHdepth cue index
INTEGERMODEdepth cue mode
REALBPLANE, FPLANEback and front depth planes
REALBSCALE, FSCALEback and front scale value
INTEGERCOLMODcolour model
INTEGERIDCOLRindirect depth cue colour
REALDCOLR(3)array of depth cue colour

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.

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

C Input Parameters

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

wsidThe 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 may be defined. Entry zero is predefined to a depth cue mode of PSUPPRESSED and cannot be changed. Entries other than zero may be changed with the SET DEPTH CUE REPRESENTATION subroutine.

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

typedef struct {
Pdcuemodemode;/∗ depth cue mode ∗/
Pfloatrefplanes[2];/∗ depth cue reference planes ∗/
Pfloatscaling[2];/∗ depth cue scaling ∗/
Pgcolrcolour;/∗ depth cue colour ∗/
} Pdcuebundl;

Pdcuemode is defined as:

typedef enum {
PSUPPRESSED,
PALLOWED
} Pdcuemode;

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 {
Pint type;/∗ indirect, RGB, CIE, HSV, HLS ∗/
union {
   Pintindex;/∗ colour table index ∗/
   struct {
Pfloatx;/∗ red, hue, etc. ∗/
Pfloaty;/∗ green, saturation, lightness, etc. ∗/
Pfloatz;/∗ blue, value, saturation, etc. ∗/
   } general;
} val;
} Pgcolr;

FORTRAN Input Parameters

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

WKIDThe identifier of the workstation for which the depth cue representation is being defined.

IDEPTH
This is a depth cue index to the workstation depth cue table.

FORTRAN Output Parameters

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

0PSUPPRDisable Depth Cueing
1PALLOWEnable Depth Cueing

BPLANE,FPLANE
The back and front depth planes. BPLANE is the back depth plane, a z value in NPC, which defines a back reference plane for depth cueing. FPLANE is the front depth plane, a z value in NPC, 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, which corresponds to the z value of the back depth cue reference plane. This value defines the portion of the primitive colours that should be combined with the depth cue colour as a function of z in NPC. FSCALE is a front scale value, between 0.0 and 1.0, which corresponds to the z value of the front depth cue reference plane. This value defines 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 which determines the type of colour to be used. If this value is PINDIR or zero, IDCOLR will contain an indexed colour value. If COLMOD is greater than zero, DCOLR will contain the depth cue colour. The valid values for COLMOD are:

0PINDIRColour Index Specified
1PRGBRed, Green, and Blue
2PCIECIE Colour Model
3PHSVHue, Saturation, and Value
4PHLSHue, Lightness, and Saturation

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

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

DCOLR(1) = Red, Hue, Etc.
DCOLR(2) = Green, Saturation, Lightness, Etc.
DCOLR(3) = Blue, Value, Saturation, Etc.

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 primitives which follow 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 (i.e., 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