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