PixelCanvasColorTable.h

Go to the documentation of this file.
00001 //# PixelCanvasColorTable.h: abstraction of color resources/allocation
00002 //# Copyright (C) 1994,1995,1996,1997,1998,1999,2000,2001
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id$
00027 
00028 #ifndef TRIALDISPLAY_PIXELCANVASCOLORTABLE_H
00029 #define TRIALDISPLAY_PIXELCANVASCOLORTABLE_H
00030 
00031 #include <casa/Arrays/Vector.h>
00032 #include <casa/Containers/List.h>
00033 #include <display/Display/Colormap.h>
00034 #include <display/Display/ColormapManager.h>
00035 #include <display/Display/DisplayEnums.h>
00036 
00037 
00038 namespace casa { //# NAMESPACE CASA - BEGIN
00039 
00040         typedef void (*PixelCanvasColorTableResizeCB)(class PixelCanvasColorTable * pccmap, uInt newSize, void * clientData, Display::RefreshReason reason);
00041 
00042 // <summary>
00043 // Abstract interface to underlying graphics library's colortable
00044 // </summary>
00045 //
00046 // <prerequisite>
00047 // <li> Knowledge of hardware Colormaps
00048 // <li> <linkto class="Colormap">Colormap</linkto>
00049 // <li> <linkto class="ColormapManager">ColormapManager</linkto>
00050 // </prerequisite>
00051 //
00052 // <etymology>
00053 // PixelCanvas table of available colors.  Note that there is still a table
00054 // of colors in RGB mode.
00055 // </etymology>
00056 //
00057 // <synopsis>
00058 //
00059 // This abstract class is communicated to by the PixelCanvas to perform color
00060 // operations.  The information in this file should not be needed to support
00061 // applications programmers, and is provided for the future maintainer of the
00062 // Display library.
00063 //
00064 // A Major role of the PixelCanvasColorTable is to dynamically allocate space
00065 // out of its own colortable allocation from the underlying graphics library
00066 // for its registered <linkto class="Colormap">Colormap</linkto>s.  It talks to
00067 // its <linkto class="ColormapManager">ColormapManager</linkto> to return the
00068 // <linkto class="Colormap">Colormap</linkto> information needed to properly
00069 // scale data values to color.  An application must know the size of the colormap
00070 // to determine the color resolution available to value-related data.
00071 //
00072 // The mapToColor functions will be needed by most image drawing and colored vector
00073 // display drawing calls to transform quantized values into color indices.
00074 //
00075 // The PixelCanvasColorTable is distinguished from the <linkto class="Colormap">
00076 // Colormap</linkto> by its functionality.  There is one and only one
00077 // PixelCanvasColorTable for each
00078 // <linkto class="PixelCanvas">PixelCanvas</linkto>.
00079 // It controls the <em>allocation</em>
00080 // of containers for colors.  It also will set the colors in the containers if the
00081 // map is in HSV or RGB mode if necessary.
00082 // If the map is in INDEX mode, you can install one or more
00083 // <linkto class = "Colormap">Colormap</linkto>s that control banks
00084 // of colors in the color table because Colormaps define the <em>colors</em>
00085 // that go into the containers of a PixelCanvasColorTable.
00086 //
00087 
00088 // </synopsis>
00089 //
00090 // <motivation>
00091 // Needed to abstract the concepts involved in color resource allocation from
00092 // the
00093 // <linkto class="PixelCanvas">PixelCanvas</linkto> user.
00094 // </motivation>
00095 //
00096 // <example>
00097 // see the <linkto class="PixelCanvas">PixelCanvas</linkto> test programs
00098 // </example>
00099 //
00100 // <todo>
00101 // <li> Implement RGB resize
00102 // </todo>
00103 //
00104 
00105         class PixelCanvasColorTable {
00106         public:
00107 
00108                 // Is the hardware colormap resizeable?  ie. is it write-only?
00109                 // Default is to return true, and derived classes should generally
00110                 // override this function.
00111                 virtual Bool staticSize() {
00112                         return True;
00113                 }
00114 
00115                 // Resize the hardware colormap.
00116                 // <group>
00117                 virtual Bool resize(uInt newSize) = 0;
00118                 virtual Bool resize(uInt nReds, uInt nGreens, uInt nBlues) = 0;
00119                 // </group>
00120 
00121                 // Install colors into the color table.  Offset is zero-based.  Colors
00122                 // are installed into the PixelCanvasColorTable until the vectors run out
00123                 // or until the end of the colortable is reached.  This has no effect if
00124                 // in real/pseudo RGB/HSV modes.  Values are clamped to [0.0,1.0].
00125                 virtual Bool installRGBColors(const Vector<Float> & r, const Vector<Float> & g,
00126                                               const Vector<Float> & b, const Vector<Float> & alpha,
00127                                               uInt offset = 0) = 0;
00128 
00129                 // Return the number of colors used to make the map.
00130                 virtual uInt nColors() const = 0;
00131 
00132                 // Return the number of colors per component used in the map.  Fails
00133                 // for non-HSV/RGB modes.
00134                 virtual void nColors(uInt &n1, uInt &n2, uInt &n3) const = 0;
00135 
00136                 // Return the depth of the map in bits
00137                 virtual uInt depth() const = 0;
00138 
00139                 // Return the number of colors that are still unallocated
00140                 virtual uInt nSpareColors() const = 0;
00141 
00142                 // Virtual destructor
00143                 virtual ~PixelCanvasColorTable();
00144 
00145                 // Add and remove resize callbacks
00146                 // PixelCanvasColorTableResizeCB is of type:
00147                 // <br>void (*)(class PixelCanvasColorTable * pcctbl, uInt newSize, void * clientData, Display::RefreshReason reason)
00148                 //
00149                 // <group>
00150                 void addResizeCallback(PixelCanvasColorTableResizeCB cb, void * clientData);
00151                 void removeResizeCallback(PixelCanvasColorTableResizeCB cb, void * clientData);
00152                 // </group>
00153 
00154                 // Function that issues resize callbacks
00155                 void doResizeCallbacks(const Display::RefreshReason
00156                                        &reason = Display::ColorTableChange);
00157 
00158                 // Register a colormap to be managed by the pixel canvas' color table
00159                 void registerColormap(Colormap * cmap, Float weight = 1.0);
00160 
00161                 // Register the <src>cmap</src> Colormap on the
00162                 // PixelCanvasColorTable, replacing the <src>cmapToReplace</src>
00163                 // Colormap if possible.
00164                 void registerColormap(Colormap *cmap, Colormap *cmapToReplace);
00165 
00166                 // Unregister a data colormap reference previously added
00167                 void unregisterColormap(Colormap * cmap);
00168 
00169                 // Return the allocation size of some Colormap
00170                 uInt getColormapSize(const Colormap * cmap) const;
00171 
00172                 // map [0,N-1] into colorpixels, where N is the current colormap size
00173                 // The values are returned as unsigned integers in their respective
00174                 // array.
00175                 // <note role="tip">The choice of what type to use should be guided by
00176                 // the number of graphics bitplanes available.  For most systems with
00177                 // 8-bit color, uChar is optimal.  Some systems with 12 bits per pixel
00178                 // with an alpha channel may require using the uLong. </note>
00179                 //
00180                 // <note role="warning">uChar type may not have enough bits
00181                 // to hold the pixel index on some high-end graphics systems </note>
00182                 // <note role="warning">uShort type may not have enough bits
00183                 // to hold the pixel index on some high-end graphics systems </note>
00184                 //
00185                 // <group>
00186                 virtual void mapToColor(const Colormap * map, Array<uChar> & outArray,
00187                                         const Array<uChar> & inArray, Bool rangeCheck = True) const = 0;
00188                 virtual void mapToColor(const Colormap * map, Array<uShort> & outArray,
00189                                         const Array<uShort> & inArray, Bool rangeCheck = True) const = 0;
00190                 virtual void mapToColor(const Colormap * map, Array<uInt> & outArray,
00191                                         const Array<uInt> & inArray, Bool rangeCheck = True) const = 0;
00192                 virtual void mapToColor(const Colormap * map, Array<uLong> & outArray,
00193                                         const Array<uLong> & inArray, Bool rangeCheck = True) const = 0;
00194                 virtual void mapToColorRGB(const Colormap* map, Array<uInt>& outArray,
00195                                                 const Array<uInt>& inArrayRed, const Array<uInt>& inArrayGreen, const Array<uInt>& inArrayBlue) const;
00196                 // </group>
00197 
00198                 // same as above except the matrix is operated on in place.  Only unsigned
00199                 // values make sense here.  I don't really know what to include here.  Maybe
00200                 // ask the code cop.
00201                 virtual void mapToColor(const Colormap * map, Array<uChar> & inOutArray,
00202                                         Bool rangeCheck = True) const = 0;
00203                 virtual void mapToColor(const Colormap * map, Array<uShort> & inOutArray,
00204                                         Bool rangeCheck = True) const = 0;
00205                 virtual void mapToColor(const Colormap * map, Array<uInt> & inOutArray,
00206                                         Bool rangeCheck = True) const = 0;
00207                 virtual void mapToColor(const Colormap * map, Array<uLong> & inOutArray,
00208                                         Bool rangeCheck = True) const = 0;
00209 
00210                 // Functions for dealing with multi-channel mapping
00211                 // <group>
00212                 // (Multichannel Color)
00213                 // Merge separate channel data into an output image.
00214                 // This function maps floating values between 0 and 1
00215                 // into a output image suitable for PixelCanvas::drawImage().
00216                 virtual void mapToColor3(Array<uLong> & out,
00217                                          const Array<Float> & chan1in,
00218                                          const Array<Float> & chan2in,
00219                                          const Array<Float> & chan3in) = 0;
00220                 virtual void mapToColor3(Array<uLong> & out,
00221                                          const Array<Double> & chan1in,
00222                                          const Array<Double> & chan2in,
00223                                          const Array<Double> & chan3in) = 0;
00224                 // </group>
00225 
00226                 // This one maps values between 0 and the integer
00227                 // maximum value for each channel into a single
00228                 // output image suitable for PixelCanvas::drawImage().
00229                 // <group>
00230                 virtual void mapToColor3(Array<uLong> & out,
00231                                          const Array<uShort> & chan1in,
00232                                          const Array<uShort> & chan2in,
00233                                          const Array<uShort> & chan3in) = 0;
00234                 virtual void mapToColor3(Array<uLong> & out,
00235                                          const Array<uInt> & chan1in,
00236                                          const Array<uInt> & chan2in,
00237                                          const Array<uInt> & chan3in) = 0;
00238                 // </group>
00239 
00240                 // (Multichannel Color)
00241                 // Transform arrays from the passed color model into
00242                 // the colormodel of the XPCCT.
00243                 // Does nothing if colorModel is Display::Index.
00244                 // It is assumed that input arrays are in the range of [0,1]
00245                 virtual Bool colorSpaceMap(Display::ColorModel,
00246                                            const Array<Float> & chan1in,
00247                                            const Array<Float> & chan2in,
00248                                            const Array<Float> & chan3in,
00249                                            Array<Float> & chan1out,
00250                                            Array<Float> & chan2out,
00251                                            Array<Float> & chan3out) = 0;
00252 
00253                 // Return whether or not a data colormap is used by this pixel canvas
00254                 Bool member(const Colormap * cmap) const;
00255 
00256                 // Return the default map.  This map is only used if no other colormaps
00257                 // are registered AND if we're in INDEX mode.
00258                 // Colormap * defaultColormap() const { return defaultColormap_; }
00259 
00260                 // Set the default colormap
00261                 void setDefaultColormap(const Colormap * map);
00262 
00263                 // Return the colormapManager used by this PCCT
00264                 ColormapManager & colormapManager() {
00265                         return dcmapMgr_;
00266                 }
00267 
00268                 // Return the color model for multichannel color
00269                 virtual Display::ColorModel colorModel() const = 0;
00270 
00271                 /*
00272                 // register a pixel canvas on this pcct
00273                 void registerPixelCanvas(const class PixelCanvas * pc);
00274                 void doRefreshCallbacks();
00275                 */
00276 
00277                 Colormap* defaultColormap() {
00278                         return defaultColormap_;
00279                 }
00280 
00281         protected:
00282 
00283                 // return the offset of a particular colormap.  This information is not
00284                 // made available to the outside caller.  Rather a function to map
00285                 // values to color is made available.
00286                 uInt getColormapOffset(const Colormap * map) const {
00287                         return dcmapMgr_.getColormapOffset(map);
00288                 }
00289 
00290                 // Abstract base class
00291                 PixelCanvasColorTable();
00292 
00293         private:
00294                 uInt getColorAmount( const uInt* posMatrix, const uInt* endMatrix,
00295                                         int shiftAmount, int colorCount )const;
00296                 // Pointer to the default colormap
00297                 Colormap* defaultColormap_;
00298 
00299                 // The colormap manager
00300                 ColormapManager dcmapMgr_;
00301 
00302                 // List of resize callbacks
00303                 List<void *> resizeCBList_;
00304                 // List of client data for resize callbacks
00305                 List<void *> clientDataList_;
00306                 // List of pixelCanvases on this color table
00307                 List<void *> pixelCanvasList_;
00308         };
00309 
00310 
00311 } //# NAMESPACE CASA - END
00312 
00313 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1