.\" ## .\" $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