NAME

SET LIGHT SOURCE REPRESENTATION - define light source representation entry in workstation table of defined light source representations

SYNOPSIS

C Syntax

void

pset_light_src_rep ( ws, index, rep )

Pint                 ws;      workstation identifier
Pint                 index;   light table index
Plight_src_bundle    * rep;   light source representation

FORTRAN Syntax

SUBROUTINE pslsr ( WKID, INDEX, LSTYPE, LDR, DATREC )

INTEGER             WKID               workstation identifier
INTEGER             INDEX              light source table index
INTEGER             LSTYPE             light source type
INTEGER             LDR                dimension of data record array
CHARACTER* 80       DATREC(LDR)        data record

Required PHIGS Operating States

(PHOP, WSOP, * ,* )

DESCRIPTION

Purpose

SET LIGHT SOURCE REPRESENTATION defines a light source representation for a specified index number on the workstation table of defined light source representations. Each integer entry on this table specifies a light source type (Ambient, Directional, Positional, or Spot) and a data record containing the parameters needed to define the light source type.

Defined light sources are activated or deactivated with the SET LIGHT SOURCE STATE subroutine. When lighting and shading are applied to a display, the currently active light sources are used, with the current surface properties and interior lighting and shading methods, to render the following area defining primitives: FILL AREA 3 ,FILL AREA SET 3 ,and FILL AREA SET 3 WITH DATA.

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 light source representation is to be defined. The workstation must have been opened with the OPEN WORKSTATION subroutine before calling SET LIGHT SOURCE REPRESENTATION.

index

The number of the entry to be defined on the table of defined light source representations, in the specified workstation state list.

rep

A pointer to light source representation. The Plight_src_bundle data structure contains values needed to define the specified type of light source representation. Plight_src_bundle is defined as:

typedef struct {

Pint                type;           /* light source type * /
Plight_src_rec      rec;            /* light source data record * /

} Plight_src_bundle;

The predefined light source types are:

1   PLIGHT_AMBIENT         Ambient light source
2   PLIGHT_DIRECTIONAL     Directional light source
3   PLIGHT_POSITIONAL      Positional light source
4   PLIGHT_SPOT            Spot light source

Plight_src_rec is defined as:

typedef union {

Pamb_light_src_rec

ambient;

Pdir_light_src_rec

directional;

Ppos_light_src_rec

positional;

Pspot_light_src_rec

spot;

} Plight_src_rec;

Pamb_light_src_rec is defined as:

typedef struct {

Pgcolr

colr;

/* light source colour * /

} Pamb_light_src_rec;

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;

Pdir_light_src_rec is defined as:

typedef struct {

Pgcolr          colr;           /* light source colour * /
Pvec3           dir;            /* light source direction * /

} Pdir_light_src_rec;

Pvec3 is defined as:

typedef struct {

Pfloat           delta_x;        /* x magnitude * /
Pfloat           delta_y;        /* y magnitude * /
Pfloat           delta_z;        /* z magnitude * /

} Pvec3;

Ppos_light_src_rec is defined as:

typedef struct {

Pgcolr          colr;           /* light source colour * /
Ppoint3         pos;            /* light source position * /
Pfloat           coef[2];        /* attenuation coefficients * /

} Ppos_light_src_rec;

Ppoint3 is defined as:

typedef struct {

Pfloat           x;      /* x coordinate * /
Pfloat           y;      /* y coordinate * /
Pfloat           z;      /* z coordinate * /

} Ppoint3;

Pspot_light_src_rec is defined as:

typedef struct {

Pgcolr          colr;           /* light source colour * /
Ppoint3         pos;            /* light source position * /
Pvec3           dir;            /* light source direction * /
Pfloat           exp;            /* concentration exponent * /
Pfloat           coef[2];        /* attenuation coefficients * /
Pfloat           angle;          /* half-cone spread angle * /

} Pspot_light_src_rec;

FORTRAN Input Parameters

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

WKID

The identifier of the workstation for which the light source representation is being set.

INDEX An index into to the light source table of the workstation state list for the entry

being set.

LSTYPE

The light source type. The predefined values are:

1   PAMB     Ambient light source
2   PDIR     Directional light source
3   PPOS     Positional light source
4   PSPOT    Spot light source

LDR

The dimension of the data record array, DATREC.

DATREC(LDR)

The data record is packed by PACK DATA RECORD. The contents depend on the light source type specified:

Ambient Light Source, Type 1

IL = the number of integers, 1 or 2

IA = an array of integers with the following values:

IA(1) = the colour model type. Valid values 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

IA(2) = the light source colour table index, if IA(1) specifies PINDIR

RL = the number of reals, 3

RA = an array of reals with the following values:

RA(1) - RA(3) =

the light source colour triple (x, y, z), if IA(1) is other than

PINDIR

Note: These values are not used if IA(1) is PINDIR.

SL = the number of strings, 0

Directional Light Source, Type 2

IL = the number of integers, 1 or 3

IA = an array of integers with the following values:

IA(1) = the colour model type

IA(2) = the colour table index, if IA(1) specifies PINDIR

RL = the number of reals, 6

RA = an array of reals with the following values:

RA(1 )- RA(3 )=

the light source colour triple (x, y, z), if IA(1 )is other than

PINDIR

RA(4 )- RA(6 )=

the light source direction (x, y, z)

SL = the number of strings, 0

Positional Light Source, Type 3

IL = the number of integers, 1 or 2

IA = an array of integers with the following values:

IA(1) = the colour model type

IA(2) = the colour table index, if IA(1) specifies PINDIR

RL = the number of reals, 8

RA = an array of reals with the following values:

RA(1) - RA(3) =

the light source colour triple (x, y, z), if IA(1) is other than

PINDIR

RA(4) - RA(6) =

the light source position (x, y, z)

RA(7) - RA(8) =

the attenuation coefficients

SL = the number of strings, 0

Spot Light Source, Type 4

IL = the number of integers, 1 or 2

IA = an array of integers with the following values:

IA(1) = the colour model type

IA(2) = the colour table index, if IA(1) specifies PINDIR

RL = the number of reals, 13

RA = an array of reals with the following values:

RA(1) - RA(3) =

the light source colour triple (x, y, z), if IA(1) is other than

PINDIR

RA(4) - RA(6) =

the light source position (x, y, z)

RA(7) - RA(9) =

the light source direction (x, y, z)

RA(10) = the concentration exponent

RA(11) - RA(12) =

the attenuation coefficients

RA(13) = the half-cone spread angle

SL = the number of strings, 0

Execution

When SET LIGHT SOURCE REPRESENTATION is called, the light source index entry in the table of defined light source representations on the workstation is set to the new attribute values.

Note: SunPHIGS defines the direction of a directional light to be the vector from the light to the object. This is the opposite of what some applications expect.

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

169

Ignoring function, the specified light direction is invalid

614

Ignoring function, the light source index is less than one

617

Ignoring function, the specified light source type is not available on the workstation

618

Ignoring function, the specified spot light spread angle is out of range

SEE ALSO

SET REFLECTANCE PROPERTIES (3PP)

SET REFLECTANCE EQUATION (3PP)

INQUIRE LIST OF LIGHT SOURCE INDICES (3PP)

INQUIRE LIGHT SOURCE REPRESENTATION (3PP)

INQUIRE LIGHT SOURCE FACILITIES (3PP)

INQUIRE PREDEFINED LIGHT SOURCE REPRESENTATION (3PP)