.\"##
.\" $XConsortium: p337,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 STATE\s+2
.TH "SET LIGHT SOURCE STATE" 3P+ "29 February 1991"
.SH NAME
SET LIGHT SOURCE STATE \- create structure element to enable and 
disable light sources  
.IX "Lighting" "SET LIGHT SOURCE STATE"
.\".IX "PHIGS Extension Functions" "SET LIGHT SOURCE STATE"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pset_light_src_state ( activation, deactivation )
Pint_list	*activation;	\fIactivation list\fP
Pint_list	*deactivation;	\fIdeactivation list\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, STOP, *)
.SH DESCRIPTION
.SS Purpose
\s-2SET LIGHT SOURCE STATE\s+2 creates an element in the
currently open structure enabling and disabling specified light
source representations on the table of defined light sources
stored on the workstation state list. The current light source
state determines the number and type of light sources used to
shade the primitives that follow in the structure network.
.SS C Input Parameters
.IP \fIactivation\fR
This is a list of light sources to be activated. This structure 
specifies both an integer value indicating the number of light source
representations to be activated and a pointer to a list specifying
the index numbers of the light source representations to be activated. 
Pint_list is defined as:
.nf
.ta .5i +\w'Pint	'u +\w'num_ints;	'u
.sp .4
typedef struct {
.sp .2
	Pint	num_ints;	/* number of light sources to activate */
	Pint	*ints;	/* list of light sources to activate */
.sp .2
} Pint_list;
.fi
.sp
.IP \fIdeactivation\fR
This is a list of light sources to be deactivated. This structure 
specifies both an integer value indicating the number of light source
representations to be deactivated and a pointer to a list specifying
the index numbers of the light source representations to be deactivated. 
Pint_list is defined as:
.nf
.ta .5i +\w'Pint	'u +\w'num_ints;	'u
.sp .4
typedef struct {
.sp .2
	Pint	num_ints;	/* number of light sources to activate */
	Pint	*ints;	/* list of light sources to activate */
.sp .2
} Pint_list;
.IP
.fi
.SS Execution
Depending on the edit mode, a \s-2SET LIGHT SOURCE STATE\s+2
element is inserted into the open structure after the element
pointer or replaces the element pointed at by the element pointer.
The element pointer is then updated to point to this 
\s-2SET LIGHT SOURCE STATE\s+2 element.
.LP
When the \s-2SET LIGHT SOURCE STATE\s+2 element is traversed, the
light source representations listed in the activation list are added to the 
current light source state entry in the 
traversal state list, and the representations listed in the deactivation
list are deleted. The light source representations are
defined with the \s-2SET LIGHT SOURCE REPRESENTATION\s+2 subroutine.
.LP
The current light source state list defines the ambient, diffuse,
and specular light sources that may be used when applying lighting
and shading to area-defining or polyline primitives. The types of 
light sources used are defined by the
\s-2SET INTERIOR SHADING METHOD\s+2 and \s-2SET POLYLINE SHADING METHOD\s+2
subroutines.
.RE
.SH ERRORS
.IP 005
Ignoring function, function requires state (\s-2PHOP,*,STOP,*\s+2)
.IP 133
Ignoring function, one of the entries in the activation list or
deactivation list is less than one (1)
.IP 135
Ignoring function, the same entry exists in both the activation
list and the deactivation list
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "SET LIGHT SOURCE REPRESENTATION (3P+)"
.SM "INQUIRE LIGHT SOURCE FACILITIES (3P+)"
.fi