.\"##
.\" $XConsortium: p336,v 5.2 94/04/17 20:58:21 rws Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         All Rights Reserved
.\"## 
.\"## Permission to use, copy, modify, and distribute this software and its 
.\"## documentation for any purpose and without fee is hereby granted, 
.\"## provided that the above copyright notice appear in all copies and that
.\"## both that copyright notice and this permission notice appear in 
.\"## supporting documentation, and that the name of Sun Microsystems,
.\"## not be used in advertising or publicity 
.\"## pertaining to distribution of the software without specific, written 
.\"## prior permission.  
.\"## 
.\"## SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
.\"## INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\"## EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\"## CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\"## USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\"## OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\"## PERFORMANCE OF THIS SOFTWARE.
.ds f \s-2SET LIGHT SOURCE REPRESENTATION\s+2
.TH "SET LIGHT SOURCE REPRESENTATION" 3P+ "29 February 1991"
.SH NAME
SET LIGHT SOURCE REPRESENTATION \- define a light source representation
entry in the workstation table of defined light source representations  
.IX "PHIGS Extension Functions" "SET LIGHT SOURCE REPRESENTATION"
.IX "Lighting" "SET LIGHT SOURCE REPRESENTATION"
.IX "Attribute Representations" "SET LIGHT SOURCE REPRESENTATION"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.5i 3i
.nf
void
pset_light_src_rep ( ws, index, rep )
Pint	ws;	\fIworkstation identifier\fP
Pint	index;	\fIlight table index\fP
Plight_src_bundle	*rep;	\fIlight source representation\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
\s-2SET LIGHT SOURCE REPRESENTATION\s+2 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 (\fIAmbient, Directional, Positional,\fP
or \fISpot\fP) and a data record containing the parameters needed to 
define the light source type.
.LP
Defined light sources are activated or deactivated with the
\s-2SET LIGHT SOURCE STATE\s+2 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:
\s-2FILL AREA 3\s+2,
\s-2FILL AREA SET 3\s+2, and 
\s-2FILL AREA SET 3 WITH DATA\s+2.
.SS C Input Parameters
.IP \fIws\fR
The workstation identifier specifies the workstation for which the light
source representation is to be defined. The workstation must have been
opened with the \s-2OPEN WORKSTATION\s+2 subroutine before calling
\s-2SET LIGHT SOURCE REPRESENTATION\s+2.
.IP \fIindex\fR
The number of the entry to be defined on the table of defined light source
representations, in the specified workstation state list.
.\"When a workstation is opened, entries 1
.\"and 2 are each initialized with the following predefined light sources:
.IP \fIrep\fR
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:
.nf
.ta .5i +1.25i  +1i   +1.25i
.sp .4
typedef struct {
.sp .2
	Pint	type;	/* light source type */
	Plight_src_rec	rec;	/* light source data record */
.sp .2
} Plight_src_bundle;
.IP
The predefined light source types are:
.sp
.nf
.ta .5i +\w'0     'u +\w'PLIGHT_DIRECTIONAL     'u
1	PLIGHT_AMBIENT		\fIAmbient Light Source\fP
2	PLIGHT_DIRECTIONAL	\fIDirectional Light Source\fP
3	PLIGHT_POSITIONAL	\fIPositional Light Source\fP
4	PLIGHT_SPOT		\fISpot Light Source\fP
.sp
.fi
.IP
Plight_src_rec is defined as:
.nf
.ta .5i +1.5i  +1i
.sp .4
typedef union {
.sp .2
	Pamb_light_src_rec	ambient;
	Pdir_light_src_rec	directional;
	Ppos_light_src_rec	positional;
	Pspot_light_src_rec	spot;
.sp .2
} Plight_src_rec;
.fi
.IP
Pamb_light_src_rec is defined as:
.nf
.ta .5i +1i  +1i   +1.25i
.sp .4
typedef struct {
.sp .2
	Pgcolr	colr;	/* light source colour */
.sp .2
} Pamb_light_src_rec;
.IP
.fi
Pgcolr is defined as:
.ta .5i +1.5i   +1i  +2i
.nf
.sp .4
typedef struct {
.sp .2
	Pint	type;	/* indirect, RGB, CIE, HSV, HLS */
	union {
	     Pint	ind;	/* index in workstation colour bundle table */
	     struct {
	          Pfloat	x;	/* red, hue, etc. */
	          Pfloat	y;	/* green, saturation, lightness, etc. */
	          Pfloat	z;	/* blue, value, saturation, etc. */
	     } general;
	} val;
} Pgcolr;
.fi
.IP
Pdir_light_src_rec is defined as:
.nf
.ta .5i +1i  +1i  +1.5i
.sp .4
typedef struct {
.sp .2
	Pgcolr	colr;	/* light source colour */
	Pvec3	dir;	/* light source direction */
.sp .2
} Pdir_light_src_rec;
.IP
.fi
Pvec3 is defined as:
.sp .2
.nf
.ta .5i +1i  +1i   +1i
.sp .2
typedef struct {	
.sp .2
	Pfloat	delta_x;	/* x magnitude */
	Pfloat	delta_y;	/* y magnitude */
	Pfloat	delta_z;	/* z magnitude */
.sp .2
} Pvec3;
.fi
.IP
Ppos_light_src_rec is defined as:
.nf
.ta .5i +1i  +1i  +1.5i
.sp .4
typedef struct {
.sp .2
	Pgcolr	colr;	/* light source colour */
	Ppoint3	pos;	/* light source position */
	Pfloat	coef[2];	/* attenuation coefficients */
.sp .2
} Ppos_light_src_rec;
.fi
.IP
Ppoint3 is defined as: 
.sp .2
.nf
.ta .5i +1i  +.5i   +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	x;	/* x coordinate */
	Pfloat	y;	/* y coordinate */
	Pfloat	z;	/* z coordinate */
.sp .2
} Ppoint3;
.fi
.IP
.bp
Pspot_light_src_rec is defined as:
.nf
.ta .5i +1i  +1i  +1.5i
.sp .4
typedef struct {
.sp .2
	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;	/* spread angle */
.sp .2
} Pspot_light_src_rec;
.fi
.IP
.SS Execution
When \s-2SET LIGHT SOURCE REPRESENTATION\s+2 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.
.SH ERRORS
.IP 003
Ignoring function, function requires state (\s-2PHOP,WSOP,*,*\s+2)
.IP 054
Ignoring function, the specified workstation is not open
.IP 059
Ignoring function, the specified workstation does not have output capability
(that is, the workstation category is neither \s-2OUTPUT\s+2,
\s-2OUTIN\s+2, nor \s-2MO\s+2)
.IP 103
Ignoring function, setting this bundle table entry would exceed the maximum
number of entries allowed in the workstation bundle table
.IP 169
Ignoring function, the specified light direction is invalid
.IP 614
Ignoring function, the light source index is less than one
.IP 617
Ignoring function, the specified light source type is not available on the
workstation
.IP 618
Ignoring function, the specified spot light spread angle is out of range
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "SET REFLECTANCE PROPERTIES (3P+)"
.SM "SET REFLECTANCE EQUATION (3P+)"
.SM "INQUIRE LIST OF LIGHT SOURCE INDICES (3P+)"
.SM "INQUIRE LIGHT SOURCE REPRESENTATION (3P+)"
.SM "INQUIRE LIGHT SOURCE FACILITIES (3P+)"
.SM "INQUIRE PREDEFINED LIGHT SOURCE REPRESENTATION (3P+)"
.fi