NAME

SET DEPTH CUE REPRESENTATION - define depth cue representation entry in workstation table of defined depth cue representations

SYNOPSIS

C Syntax

void

pset_dcue_rep ( ws, index, rep )

Pint             ws;      workstation identifier
Pint             index;   depth cue bundle index
Pdcue_bundle     * rep;   depth cue representation pointer

FORTRAN Syntax

SUBROUTINE psdcr ( WKID, IDEPTH, MODE, BPLANE, FPLANE, BSCALE, FSCALE, COLTYPE, IDCOLR, DCOLR )

INTEGER      WKID                  workstation identifier
INTEGER      IDEPTH                depth cue index
INTEGER      MODE                  depth cue mode
REAL         BPLANE, FPLANE        back and front depth planes
REAL         BSCALE, FSCALE        back and front scale value
INTEGER      COLTYPE               colour type
INTEGER      IDCOLR                indirect depth cue colour
REAL         DCOLR(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 PLUS and is not part of the PHIGS standard.

C Input Parameters

ws

The 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.

index

The 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.

rep

A 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_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;

Refplanes and scaling entries of zero are back reference plane and corresponding scaling factors. Refplanes and scaling entries of one 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;

Constants defined for colour type are:

0   PINDIRECT         Indirect
1   PMODEL_RGB        Red, Green, Blue
2   PMODEL_CIELUV     CIE
3   PMODEL_HSV        Hue, Saturation, Value

4

PMODEL_HLS

Hue, Lightness, Saturation

FORTRAN Input Parameters

The following data types are predefined in phigs77.h.

WKID

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

IDEPTH

The 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:

0   PSUPPR     Disable Depth Cueing
1   PALLOW     Enable Depth Cueing

BPLANE,

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,

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.

COLTYPE

The colour type. If this value is PINDIR or zero, then IDCOLR contains an indexed colour value. If COLTYPE is greater than zero, then DCOLR contains the depth cue colour. The valid values for COLTYPE are:

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

IDCOLR

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

DCOLR(3)

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

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

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

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

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 back reference plane. The second scaling value specifies the portion of primitive colour applied at, or behind, the front 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 0 and 1 are initialized with the following representation:

                             Entry 0        Entry 1

depth cue mode

SUPPRESSED

ALLOWED

depth cue reference planes   0.0 ,1.0        0.0 ,1.0
depth cue scaling            1.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

003

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

054

Ignoring function, the specified workstation is not open

059

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

103

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

110

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

120

Ignoring function, the depth cue index is less than one

130

Ignoring function, invalid reference planes; DQMIN > DQMAX

SEE ALSO

OPEN WORKSTATION (3P)

SET DEPTH CUE INDEX (3PP)

INQUIRE DEPTH CUE REPRESENTATION (3PP)