.\"##
.\" $XConsortium: p300,v 5.2 94/04/17 20:57:55 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.
.TH "SET COLOUR REPRESENTATION" 3P "29 February 1991"
.SH NAME
SET COLOUR REPRESENTATION \- define a colour representation entry in the workstation's colour table
.IX "Attribute Representations" "SET COLOUR REPRESENTATION"
.IX "Colour" "SET COLOUR REPRESENTATION"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pset_colr_rep ( ws, index, rep )
Pint	ws;	\fIworkstation identifier\fP
Pint	index;	\fIcolour bundle index\fP
Pcolr_rep	*rep;	\fIcolour representation pointer\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, WSOP, *, *)
.SH DESCRIPTION
.SS Purpose
\s-2SET COLOUR REPRESENTATION\s+2
defines an entry in the workstation's colour table.  
Each entry in this table contains three component values,
defining a colour in the current colour model.  
.\"TRUE: \fBNote:\fP Only the RGB colour model is supported in this release.
.\"PHIGS+:	The table of defined colours is used to specify colour
.\"PHIGS+:	attributes when the appropriate CSF (\s-2POLYLINE,
.\"PHIGS+:	POLYMARKER, TEXT, INTERIOR,\s+2 or \s-2EDGE\s+2) is set to
.\"PHIGS+:	\s-2INDEXED\s+2.
The colour representations apply to all primitives.  
.LP
\fBNote:\fP \s-2PEX-SI\s+2 presently supports only the \s-2RGB\s+2 colour model.
.SS C Input Parameters
.IP \fIws\fP
The identifier of the workstation for which the colour
representation is being defined.  
.IP \fIindex\fP
The \fIcolour index\fP of the entry being defined.  
.IP \fIrep\fP
A pointer to a union containing the 
three \fIcolour components\fP defining the colour representation. 
Pcolr_rep is defined in phigs.h  as follows:  
.ta .5i +1i +1i
.nf
.sp .2
typedef union {
.sp .2
	Prgb	rgb;	/* Red Green Blue colour specification */
	Pcieluv	cieluv;	/* CIE L*U*V* colour specification */
	Phls	hls;	/* Hue Lightness Saturation colour specification */
	Phsv	hsv;	/* Hue Saturation Value colour specification */
	Pdata	unsupp;	/* Colour in unsupported colour model */
.sp .2
} Pcolr_rep;
.sp .2
.fi
.IP
Prgb is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	red;	/* red, hue, etc */
	Pfloat	green;	/* green, saturation, lightness, etc */
	Pfloat	blue;	/* blue, value, saturation, etc */
.sp .2
} Prgb;
.fi
.IP
Pcieluv is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	cieluv_x;	/* x coefficient */
	Pfloat	cieluv_y;	/* y coefficient */
	Pfloat	cieluv_y_lum;	/* y luminance */
.sp .2
} Pcieluv;
.fi
.IP
Phls is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	hue;	/* hue */
	Pfloat	lightness;	/* lightness */
	Pfloat	satur;	/* saturation */
.sp .2
} Phls;
.fi
.IP
Phsv is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	Pfloat	hue;	/* hue */
	Pfloat	satur;	/* saturation */
	Pfloat	value;	/* value */
.sp .2
} Phsv;
.fi
.IP
Pdata is defined in phigs.h as follows:
.nf
.ta .5i +1i +1i
.sp .2
typedef struct {
.sp .2
	size_t	size;	/* size of data */	
	char	*data	/*pointer to data */
.sp .2
} Pdata;
.fi
.SS Execution
When \s-2SET COLOUR REPRESENTATION\s+2 is called,
the colour index entry in
the table of defined colour representations on the workstation is set to
the three colour components specified.  
.LP
For the \s-2RGB\s+2 colour model, the only one implemented in this release,
the range for these colour components is 0 to 1:  
0 sets the colour component off;  
1 sets the colour component at full intensity.
.\"PHIGS+:	When the Colour Source Flag (CSF) for \s-2POLYLINE,
.\"PHIGS+:	POLYMARKER, TEXT, INTERIOR,\s+2or \s-2EDGE\s+2 is set to
.\"PHIGS+:	\s-2INDEXED\s+2, the colour for the corresponding
.\"PHIGS+:	primitive is specified as an index into this colour
.\"PHIGS+:	table.
.\"PHIGS+:	.LP
.\"PHIGS+:	When CSF \(eq \s-2INDEXED\s+2, the primitive's colour
.\"PHIGS+:	Aspect Source Flag (ASF) determines whether the current
.\"PHIGS+:	index value is taken from the currently selected defined
.\"PHIGS+:	representation for the primitive (ASF \(eq
.\"PHIGS+:	\s-2BUNDLED\s+2), or from the current colour index
.\"PHIGS+:	individually specified for the primitive (ASF \(eq
.\"PHIGS+:	\s-2INDIVIDUAL\s+2).
.LP
The colour table is numbered from 0, the background colour,
to a workstation-dependent maximum.  
.SH ERRORS
.IP 003
Ignoring function, function requires state 
(\s-2PHOP\s+2, \s-2WSOP\s+2, \s-2*\s+2, \s-2*\s+2)
.IP 054
Ignoring function, the specified workstation is not open
.IP 059
Ignoring function, the specified workstation does not have output capability
(in other words, the workstation category is neither \s-2OUTPUT\s+2, \s-2OUTIN\s+2, nor \s-2MO\s+2) 
.IP 113
Ignoring function, the colour index value is less than zero
.IP 103
Ignoring function, setting this bundle table entry would exceed
the maximum number of entries allowed in the workstation bundle table
.IP 118
Ignoring function, one of the components of the colour specification
is out of range.  
The valid range is dependent upon the current colour model
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "PHIGS WORKSTATION DESCRIPTION TABLE (7P)"
.SM "WORKSTATION TYPE SET (3P)"
.SM "SET POLYLINE COLOUR INDEX (3P)"
.SM "SET POLYMARKER COLOUR INDEX (3P)"
.SM "SET TEXT COLOUR INDEX (3P)"
.SM "SET INTERIOR COLOUR INDEX (3P)"
.SM "SET EDGE COLOUR INDEX (3P)"
.SM "SET COLOUR MODEL (3P)"
.SM "INQUIRE COLOUR REPRESENTATION (3P)"
.SM "INQUIRE PREDEFINED COLOUR REPRESENTATION (3P)"
.fi