.\" ##
.\" $XConsortium: p407,v 5.2 94/04/17 20:59:13 rws Exp $
.\" ##
.\" ## 
.\" ## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. and the X Consortium.
.\" ## 
.\" ##                         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 names of Sun Microsystems
.\" ## and the X Consortium 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 "COLOUR" 7P "29 February 1991"
.SH NAME
COLOUR \- introduction to using colour in the \s-2PEX-SI\s+2
.IX "COLOUR"
.IX "Colour" "COLOUR"
.SH DESCRIPTION
This page provides an overview of using
the capabilities of a colour system
from the \s-2PHIGS API\s+2 to \s-2PEX\s+2.
The topics covered are:
.nf
.RS
	\(bu  Standard \s-2PHIGS\s+2: Indexed Colour 
	\(bu  \s-2PHIGS\s+2+: General Colour 
	\(bu  Setting a Workstation's Colour Table
	\(bu  How Colour Maps Are Set Up 
.RE
.fi
.\" -------
.LP
.\"
.\"
.\" NOTE ABOUT SPELLING: colormap is not a PHIGS word, but a SunView and
.\" general graphics term, so it has the SunView and general spelling.
.\" Everything else is a PHIGS term, so we spell with the British `u'.
.\"
.\"
.\" .SH ABBREVIATIONS
.\" ****************************************************
.SS Standard PHIGS: Indexed Colour
Standard \s-2PHIGS\s+2 supports only 
.IR "indexed colour" .
Structure elements select a colour for a primitive by using an integer
colour index,
such as that
selected by \s-2SET POLYLINE COLOUR INDEX(3P)\s+2.
When a primitive is displayed on a workstation, the
colour index is used to select a colour value (called a
colour representation)
from the workstation's
colour table.
The colour representation is what is actually seen by the observer.
The default colour index for all primitives is 1.
.\" -------
.SS PHIGS PLUS: General Colour
\s-2PHIGS PLUS\s+2 allows the specification  of
colour either as indexed colours, or as \s-2RGB\s+2 colours directly.  
When a colour is specified as an index, it is called \fIindirect colour\fP,
since the colours are indirectly specified through the workstation colour table.
When a colour is specified as an \s-2RGB\s+2 triple, it is called 
\fIdirect colour\fP. 
General colour is an abstraction that allows colour or direct colour
to be specified as a single aspect.
A general colour consists of a type and a value. 
If the type is indirect,
then the value is interpreted as an index into the workstation colour table.
If the type \s-2RGB\s+2, then the value is interpreted as an \s-2RGB\s+2 value.
In addition to \s-2RGB\s+2 type, \s-2PHIGS\s+2+ allows specification of direct color
in other types, for example \s-2HLS, HSV\s+2 and \s-2CIELUV\s+2. In the \s-2PEX-SI\s+2,
however, only the type \s-2RGB\s+2 is allowed.
.LP
Using the \s-2PEX-SI\s+2 primitives and attributes,
the colour for a primitive can be set using either attribute elements, such as
\s-2SET POLYLINE COLOUR (3P+)\s+2, or primitives with one or more colours as 
part of 
the primitive, such as \s-2POLYLINE SET 3 WITH DATA (3P+)\s+2.
In either case, the colour is specified as a general colour, so that an
index or direct colour can be used.
This functionality supercedes the standard \s-2PHIGS\s+2 functionality.
Standard \s-2PHIGS\s+2 primitives will be rendered using the \s-2PHIGS\s+2+
attributes, and standard \s-2PHIGS\s+2 attributes affect \s-2PHIGS\s+2+ 
primitives. For example, 
\s-2SET POLYLINE COLOUR INDEX(3P)\s+2 is
equivalent to calling \s-2SET POLYLINE COLOUR(3P+)\s+2 with the type set
to indirect, both elements set the same attribute.
The default colour for all primitives is indirect colour, index 1.
If a primitive or attribute specifies direct colour on an indexed colour 
workstation, then \fIindirect colour, index 1\fP is used instead.
.\" -------
.\"
.SS Setting a Workstation's Colour Table
In \s-2PHIGS\s+2, an application can use the function 
\s-2SET COLOUR REPRESENTATION\s+2 to specify a colour 
representation by a triple of real values whose meaning
depends on the current colour model.
\s-2PEX-SI\s+2 supports only the \s-2RGB\s+2 colour model.
The colour coordinate space is [0,1] in all three dimensions.
No intensity is 0.0 and is mapped to X11 colour value 0.
Maximum intensity is 1.0  and is mapped to X11 
colour value 65535.  The \s-2RGB\s+2
values for the default colour definitions are given above.
.LP
A change to a colour representation will show up during the next 
regeneration.
.\" -------
.LP
A \s-2PHIGS\s+2 application can inquire for any colour index, either the value
it sets into the workstation's colour table or the values that will be
\fIRealized\fP on the display, after mapping to available X11
colour values.  See \s-2INQUIRE COLOUR REPRESENTATION (3P)\s+2.
.\" -------
.LP
Other colour models \s-2PHIGS\s+2+ defines are \s-2CIE\s+2 (\fICommission
Internationale de l'Eclairage's\fP universal colour definition system),
\s-2HSV\s+2 (Hue, Saturation, and Value), and \s-2HLS\s+2 
(Hue, Lightness, and Saturation).
.\" -------
.LP
Colour representations 0 and 1 can be set on a monochrome workstation,
to produce either normal or inverse video.
.\" ****************************************************
.bp
.SS How Colormaps Are Set Up
.LP
The \s-2API\s+2 tries to manage \s-2PEX\s+2 colour and colour
approximation lookup tables and \s-2X\s+2 colormaps when
implementing the \s-2PHIGS\s+2 colourmap.
Ideally, you should take the following steps before creating a window:
.sp .5v
.in +0.5i
.ta +0.2i
.ti -0.2i
1.	Find the most appropriate visual.
.sp .5v
.ti -0.2i
2.	See if there is a StandardColormap property defined on that visual.
.sp .5v
.ti -0.2i
3.	Set up the colormap on that visual or use an existing colormap.
.LP
However, \s-2X\s+2 doesn't provide a mechanism by which 
StandardColormap properties can be queried on an individual visual class 
if a window on that visual doesn't exist. Therefore, heursitics are used 
heavily to determine this. The following process takes place.
.sp .5v
.in +0.5i
.ta +0.2i
.ti -0.2i
1.	If the workstation is of type \fIx_tool\fR, determine the ``best''
visual for \s-2PEX\s+2 and open the window on that visual. The best visual
is the avaiable visual with the largest colormap size and the highest
numbered class (DirectColor > TrueColor > PseudoColor > StaticColor).
As an attempt to cut down on colormap flashing, the default visual 
is used if it has a StandardColormap with at least the same number 
of entries as the best visual.
.IP
If the workstation is of type \fIx_drawable\fR, it is the application's
responsibility to determine the most appropriate visual and
open up the window on that visual.
.IP
An error is returned if a read-only visual with no StandardColormaps
defined is available.
.sp .5v
.ti -0.2i
2.	The StandardColormap's colorcube is used if it is large enough
to hold a 5/9/5 colorcube for an 8-bit display. The characteristics
of the StandardColormap are set in the workstation's ColourApprox
lookup table. 
.IP
If there is no StandardColormap defined, an attempt is made to define
a contiguous colormap in the existing colormap using \fIXallocColorCells()\fR.
If this fails, than a new colormap is created. In either case, the
colormap is filled with the appropriate entries and the ColorApprox
lookup table is set.  The colorcube is set up to use about the same
percentage of the colormap that a 5/9/5 colorcube uses of a 256 entry
colormap (about 85%). For example, a 7/14/7 colorcube is used in
a colormap which has 1024 entries.
.\" ****************************************************
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "INQUIRE COLOUR FACILITIES (3P)"
.SM "INQUIRE COLOUR MODEL FACILITIES (3P)"
.SM "INQUIRE DIRECT COLOUR MODEL FACILITIES (3P+)"
.SM "SET COLOUR MODEL (3P)"
.SM "SET COLOUR REPRESENTATION (3P)"
.SM "INQUIRE COLOUR REPRESENTATION (3P)"
.SM "INQUIRE PREDEFINED COLOUR REPRESENTATION (3P)"
.SM "SET POLYLINE COLOUR INDEX (3P)"
.SM "SET POLYLINE COLOUR (3P+)"
.fi
.SH BUGS
The
.SM PHIGS
standard uses the \(lqinternational\(rq (in other words, British) 
spelling of \(lqcolour.\(rq
X11 and American usage spell \(lqcolormap\(rq without the
\(lqu.\(rq


