@c color.texi
     
@c This file is part of the 3DLDF User and Reference Manual.
@c Copyright (C) 2003, 2004 Laurence D. Finston 
@c See the section "GNU Free Documentation License" in the file 
@c fdl.texi for copying conditions.

@c $Id: color.texi,v 1.4 2004/01/12 18:33:22 lfinsto1 Exp lfinsto1 $

@node Color Reference, Input and Output, System Information, Top
@chapter Color Reference
  
@tindex Color
Class @code{Color} is defined in @file{colors.web}.

@menu
* Color Data Members::          
* Color Constructors and Setting Functions::  
* Color Operators::             
* Modifying Colors::            
* Showing Colors::              
* Querying Colors::             
* Defining and Initializing Colors::  
* Namespace Colors::            
@end menu
      
@node Color Data Members, Color Constructors and Setting Functions, Color Reference, Color Reference
@section Data Members

@deftypevar string name 
The name of the @code{Color}.
@end deftypevar                                                      

@deftypevar bool use_name
If @code{true}, @code{name} is written to @code{out_stream} when the
@code{Color} is used for drawing or filling.  Otherwise, the 
@cindex RGB (red-green-blue) 
RGB (red-green-blue) values are written to @code{out_stream}.
@end deftypevar                                                      

@deftypevar bool on_free_store
@code{true}, if the @code{Color} has been created by
@code{create_new<Color>()}, which allocates memory for the 
@code{Color} on the free store.  Otherwise @code{false}.  
@code{Colors} should only ever be dynamically allocated by using
@code{create_new<Color>()}. 
@xref{Color Constructors and Setting Functions,,
Color Reference;;Constructors and Setting Functions}. 
@end deftypevar                                                      

@deftypevar  real red_part
@deftypevarx real green_part
@deftypevarx real blue_part
The RGB (red-green-blue) values of the @code{Color}.  
A @code{real} value @math{r} is valid for these variables if and 
only if 
@c
@iftex
@tex
$0 \le r \le 1$.
@end tex
@end iftex
@c
@ifnottex
@math{0 <= r <= 1}.
@end ifnottex
@c
@end deftypevar                                                      

@node Color Constructors and Setting Functions, Color Operators, Color Data Members, Color Reference
@section Constructors and Setting Functions

@deftypefn {Default constructor} void Color (void)
Creates a @code{Color} and initializes its @code{red_part}, 
@code{green_part}, and @code{blue_part} to 0.  @code{use_name} and
@code{on_free_store} are set to @code{false}.  
@end deftypefn

@deftypefn {Copy constructor} void Color ({const Color&} @var{c}, [{const string} @var{n} = "", [{const bool} @var{u} = @code{true}]])
Creates a @code{Color} and makes it a copy of @var{c}.  If @var{n} is
not the empty string and @var{u} is @code{true}, @code{use_name} is set
to @code{true}.  Otherwise, its set to @code{false}.  
@end deftypefn 

@deftypefn {Constructor} void Color ({const string} @var{n}, {const unsigned short} @var{r}, {const unsigned short} @var{g}, {const unsigned short} @var{b}, [{const bool} @var{u} = @code{true}])
Creates a @code{Color} with name @var{n}.  Its @code{red_part}, 
@code{green_part}, and @code{blue_part} are set to 
@math{r/255.0}, @math{g/255.0}, and @math{b/255.0}, 
respectively.
@code{use_name} is set to @var{u}.
@end deftypefn 

@deftypefn {Setting function} void set ({const string} @var{n}, {const unsigned short} @var{r}, {const unsigned short} @var{g}, {const unsigned short} @var{b}, [{const bool} @var{u} = @code{false}])
Corresponds to the constructor above, except that @var{u} is @code{false} by default.  
@end deftypefn 

@deftypefn {Constructor} void Color ({const real} @var{r}, {const real} @var{g}, {const real} @var{b})
Creates an unnamed @code{Color} using the @code{real} values @var{r},
@var{g}, and @var{b} for its @code{red_part}, @code{green_part}, and
@code{blue_part}, respectively.
@end deftypefn 

@deftypefn {Setting function} void set ({const real} @var{r}, {const real} @var{g}, {const real} @var{b})
Corresponds to the constructor above.
@end deftypefn 

@deftypefn {Template specializations} Color* create_new<Color> ({const Color*} @var{c})
@c
@deftypefnx {} Color* create_new<Color> ({const Color&} @var{c})
@c
Pseudo-constructors for dynamic allocation of @code{Colors}.
They create a @code{Color} on the free store and allocate memory for it using 
@code{new(Color)}.  They return a pointer to the new @code{Color}.  

If @var{c} is a non-zero pointer or a reference,
the new @code{Color} will be a copy of
@var{c}.  If the new object is not meant to be a
copy of an existing one, @samp{0} must be passed to
@code{create_new<Color>()} as its argument.
@xref{Dynamic Allocation of Shapes}, for more information. 

@c !! TO DO: 
This function is used in the drawing and filling functions for
@code{Path} and @code{Solid}.  @code{Point::drawdot()} should be changed
to use it too, but I haven't gotten around to doing this yet.
@end deftypefn 

@node Color Operators, Modifying Colors, Color Constructors and Setting Functions, Color Reference
@section Operators

@deftypefn {Assignment operator} void operator= ({const Color&} @var{c})
Sets @code{name} to the empty @code{string}, @code{use_name} to
@code{false}, and @code{red_part}, @code{green_part}, and
@code{blue_part} to @var{c}.@code{red_part}, @var{c}.@code{green_part}, and
@var{c}.@code{blue_part}, respectively.
@end deftypefn 

@deftypefn {@code{const} operator} bool operator== ({const Color&} @var{c})
Equality operator.  Returns @code{true}, if the @code{red_parts},
@code{green_parts}, and @code{blue_parts} of @code{*this} and @var{c}
are equal, otherwise @code{false}.  The @code{names} and
@code{use_names} are not compared.  
@end deftypefn 

@deftypefn {@code{const} operator} bool operator!= ({const Color&} @var{c})
Inequality operator.  Returns @code{false}, if the @code{red_parts}, 
@code{green_parts}, and @code{blue_parts} of @code{*this} and @var{c}
are equal, otherwise @code{true}.  The  @code{names} and
@code{use_names} are not compared. 
@end deftypefn 

@deftypefn {Non-member function} ostream& operator<< (ostream& @var{o}, {const Color&} @var{c})
Output operator.  Writes the MetaPost code for the @code{Color} to
@code{out_stream} when a @code{Picture} is output.  This occurs when
the @code{Color} has been used as an argument to 
drawing or filling functions.

If @code{use_name} is @code{true}, @code{name} is written to
@code{out_stream}.  Otherwise, 
``(@code{red_part}, @code{green_part}, @code{blue_part})'' is written to
@code{out_stream}. 
@end deftypefn 


@node Modifying Colors, Showing Colors, Color Operators, Color Reference
@section Modifying 

@deftypefun void set_name ({const string} @var{s})
Sets @code{name} to @var{s}.  @code{use_name} is not reset. 
@end deftypefun 

@deftypefun void set_use_name ({const bool} @var{b})
Sets @code{use_name} to @var{b}.
@end deftypefun 

@deftypefun void modify ({const real} @var{r}, [{const real} @var{g} = 0, [{const real} @var{b} = 0]])
Adds @var{r}, @var{g}, and @var{b} to @code{red_part},
@code{green_part}, and @code{blue_part}, respectively.  Following the
addition, if @code{red_part}, @code{green_part}, and/or @code{blue_part}
is greater than 1, it is reduced to 1.  If it is less than 0, it is
increased to 0.
@end deftypefun 

@deftypefun void set_red_part ({const real} @var{q})
@deftypefunx void set_green_part ({const real} @var{q})
@deftypefunx void set_blue_part ({const real} @var{q})
Let @math{p} stand for @code{red_part},
@code{green_part}, or @code{blue_part}, depending upon which function is
used. 
If 
@iftex 
@tex
$0\le q\le 1$, 
@end tex
@end iftex
@ifnottex 
@math{0 <= q <= 1}, 
@end ifnottex
@c
@math{p} is set to @math{q}.  If 
@math{q < 0}, @math{p} is set to 0.
If @math{q > 1}, @math{p} is set to 1.
@end deftypefun 

@comment  node-name,  next,  previous,  up
@node Showing Colors, Querying Colors, Modifying Colors, Color Reference
@section Showing

@deftypefn {@code{const} function} void show ([string @var{text} = ""])
Prints information about the @code{Color} to standard output.
If @var{text} is not the empty @code{string}, prints @var{text} on a
line of its own.  Otherwise, it prints ``Color:''.  Then it prints
@code{name}, @code{use_name}, @code{red_part}, @code{green_part}, and
@code{blue_part}.
@end deftypefn 

@node Querying Colors, Defining and Initializing Colors, Showing Colors, Color Reference
@section Querying

@deftypefn {@code{const} function} bool is_on_free_store (void)
Returns @code{on_free_store}.  This will only be true, if the
@code{Color} was created by @code{create_new<Color>()}. 
@xref{Color Constructors and Setting Functions,,Color Reference; 
Constructors and Setting Functions}.  
@end deftypefn 

@deftypefn {Inline @code{const} function} real get_red_part ([bool @var{decimal} = @code{false}])
@deftypefnx {Inline @code{const} function} real get_green_part ([bool @var{decimal} = @code{false}])
@deftypefnx {Inline @code{const} function} real get_blue_part ([bool @var{decimal} = @code{false}])
These functions return the @code{red_part}, @code{green_part}, or
@code{blue_part} of the @code{Color}, respectively.  If @var{decimal} is
@code{false} (the default), the actual @code{real} value of the ``part''
is returned.  Otherwise, the corresponding whole number 
@math{n} such that 
@c
@iftex
@tex
$0\le n\le 255$ 
@end tex
@end iftex
@c
@ifnottex
@math{0 <= n <= 255}
@end ifnottex
@c
is returned.
@end deftypefn 

@deftypefn {@code{const} function} bool get_use_name (void)
Returns @code{use_name}.
@end deftypefn 

@deftypefn {Inline @code{const} function} string get_name (void)
Returns @code{name}.
@end deftypefn 

@node Defining and Initializing Colors, Namespace Colors, Querying Colors, Color Reference
@section Defining and Initializing Colors

@deftypefn {@code{const} function} void define_color_mp ()
Writes MetaPost code to @code{out_stream}, in order to define objects of
type  @code{color} within MetaPost, and set their @code{redparts},
@code{greenparts}, and @code{blueparts}.  
@end deftypefn 

@deftypefn {Static function} void initialize_colors (void)
Calls @code{define_color_mp()} (described above) for the 
@code{Colors} that are defined in @code{namespace Colors}
(@pxref{Namespace Colors}). 
@end deftypefn 

@node Namespace Colors,  , Defining and Initializing Colors, Color Reference
@section Namespace Colors.

@deftypevr   {Constant} {const Color} red
@deftypevrx  {Constant} {const Color} green
@deftypevrx  {Constant} {const Color} blue
@deftypevrx  {Constant} {const Color} cyan
@deftypevrx  {Constant} {const Color} yellow
@deftypevrx  {Constant} {const Color} magenta
@deftypevrx  {Constant} {const Color} orange_red
@deftypevrx  {Constant} {const Color} violet_red
@deftypevrx  {Constant} {const Color} pink
@deftypevrx  {Constant} {const Color} green_yellow
@deftypevrx  {Constant} {const Color} orange
@deftypevrx  {Constant} {const Color} violet
@deftypevrx  {Constant} {const Color} purple
@deftypevrx  {Constant} {const Color} blue_violet
@deftypevrx  {Constant} {const Color} yellow_green
@deftypevrx  {Constant} {const Color} black
@deftypevrx  {Constant} {const Color} white
@deftypevrx  {Constant} {const Color} gray
@deftypevrx  {Constant} {const Color} light_gray
@c
These constant @code{Colors} can be used in drawing and filling
commands.
@end deftypevr

@deftypevr  {Constant} {const Color} default_background
The default background color.  Equal to @code{white} per default.
@end deftypevr

@deftypevr {Pointer} {const Color*} background_color
Points to @code{default_background} by default.  
@end deftypevr

@deftypevr {Pointer} {const Color*} default_color
Points to @code{black} by default.
@end deftypevr

@deftypevr {Pointer} {const Color*} help_color 
Points to @code{green} by default.  
@end deftypevr

The following vectors of pointers to @code{Color} can be used in the
drawing and filling functions for @code{Solid} 
(@pxref{Drawing and Filling Solids,,Solid Reference; Drawing and Filling}). 
  
@deftypevr {Vector} {const vector <const Color*>} default_color_vector
Contains one pointer, namely @code{default_color}.  
@end deftypevr

@deftypevr {Vector} {const vector <const Color*>} help_color_vector
Contains one pointer, namely @code{help_color}.  
@end deftypevr

@deftypevr {Vector} {const vector <const Color*>} background_color_vector
Contains one pointer, namely @code{background_color}.  
@end deftypevr



