SET LIGHT SOURCE REPRESENTATION(3P+) — MISC. REFERENCE MANUAL PAGES

NAME

SET LIGHT SOURCE REPRESENTATION − define a light source representation entry in the workstation table of defined light source representations

SYNOPSIS

C Syntax

void
psetlightsrcrep ( wsid, index, rep )
Pintwsid;workstation identifier
Pintindex;light table index
Plightsrcbundl∗rep;light source representation

FORTRAN Syntax

SUBROUTINE pslsr ( WKID, INDEX, LSTYPE, LDR, DATREC )
INTEGERWKIDworkstation identifier
INTEGERINDEXlight source table index
INTEGERLSTYPElight source type
INTEGERLDRdimension 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+ 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 light source representation is to be defined. The workstation must have been opened with the OPEN WORKSTATION subroutine before calling SET LIGHT SOURCE REPRESENTATION.

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

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

typedef struct {
Pinttype;/∗ light source type ∗/
Plightsrcrecrec;/∗ light source data record ∗/
} Plightsrcbundl;

Plightsrcrec is defined as:

typedef union {
Pamblightsrcrecambient;
Pdirlightsrcrecdirectional;
Pposlightsrcrecpositional;
Pspotlightsrcrecspot;
} Plightsrcrec;

Pamblightsrcrec is defined as:

typedef struct {
Pgcolrcolour;/∗ light source colour ∗/
} Pamblightsrcrec;

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;

Pdirlightsrcrec is defined as:

typedef struct {
Pgcolrcolour;/∗ light source colour ∗/
Pvector3dir;/∗ light source direction ∗/
} Pdirlightsrcrec;

Pgcolr is defined above. Pvector3 is defined as:

typedef struct {
Pfloatx;/∗ x magnitude ∗/
Pfloaty;/∗ y magnitude ∗/
Pfloatz;/∗ z magnitude ∗/
} Pvector3;

Pposlightsrcrec is defined as:

typedef struct {
Pgcolrcolour;/∗ light source colour ∗/
Ppoint3pos;/∗ light source position ∗/
Pfloatcoef[2];/∗ attenuation coefficients ∗/
} Pposlightsrcrec;

Pgcolr is defined above.

Ppoint3 is defined as:

typedef struct {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
Pfloatz;/∗ z coordinate ∗/
} Ppoint3;

Pspotlightsrcrec is defined as:

typedef struct {
Pgcolrcolour;/∗ light source colour ∗/
Ppoint3pos;/∗ light source position ∗/
Pvector3dir;/∗ light source direction ∗/
Pfloatexp;/∗ concentration exponent ∗/
Pfloatcoef[2];/∗ attenuation coefficients ∗/
Pfloatangle;/∗ spread angle ∗/
} Pspotlightsrcrec;

Pgcolr, Ppoint3, and Pvector3 are defined above.

FORTRAN Input Parameters

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

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

1PAMBAmbient Light Source
2PDIRDirectional Light Source
3PPOSPositional Light Source
4PSPOTSpot Light Source

LDRThe 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:
0PINDIRColour Index Specified
1PRGBRed, Green, and Blue
2PCIECIE Colour Model
3PHSVHue, Saturation, and Value
4PHLSHue, 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 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, 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 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.

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 capabitlity (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

614Ignoring function, the light source index is less than one

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

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

Museum