PixelCanvas.h

Go to the documentation of this file.

//# PixelCanvas.h: Base class defining interface to PixelCanvases
//# Copyright (C) 1995,1996,1997,1998,1999,2000,2001,2002,2003
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//#        Internet email: aips2-request@nrao.edu.
//#        Postal address: AIPS++ Project Office
//#                        National Radio Astronomy Observatory
//#                        520 Edgemont Road
//#                        Charlottesville, VA 22903-2475 USA
//#
//# $Id$

#ifndef DISPLAY_PIXELCANVAS_H
#define DISPLAY_PIXELCANVAS_H

#include <casa/aips.h>
#include <casa/Containers/List.h>
#include <display/Display/DisplayEnums.h>
#include <display/Display/PixelCanvasColorTable.h>
#include <display/Display/PCVGBuffer.h>
#include <display/Display/DLFont.h>

namespace casa { //# NAMESPACE CASA - BEGIN

        template <class T> class Vector;
        template <class T> class Matrix;
        class Colormap;
        class PCMotionEH;
        class PCPositionEH;
        class PCRefreshEH;


// <summary>
// Base class defining interface to pixel-based output devices.
// </summary>
//
// <prerequisite>
// <li> <linkto class="Colormap">Colormap</linkto>
// <li> <linkto class="PixelCanvasColorTable">PixelCanvasColorTable</linkto>
// <li> <linkto class="PCMotionEH">PCMotionEH</linkto>
// <li> <linkto class="PCRefreshEH">PCRefreshEH</linkto>
// <li> <linkto class="PCPositionEH">PCPositionEH</linkto>
// </prerequisite>
//
// <etymology>
// PixelCanvas is the mechanism for drawing on the screen.
// </etymology>
//
// <synopsis>
// The philosophy of the PixelCanvas is to provide flexible fast interface to
// an underlying graphics system in terms of integer pixel positions and
// color values.  The interface should be as simple as possible and not demand
// complicated structures on its interface.
//
// The PixelCanvas performs minimal management, leaving up to the derived classes
// for most of the work required to interface to the underlying graphics library.
//
// To make it flexible, the fundamental interface accepts pointers to arrays of all
// the scalar AIPS++ types.  The Bool type is not acceptable at the PixelCanvas
// level because it cannot be used to represent a color index, as are the two
// complex number types.
//
// To make it fast, a caching mechanism is used to allow display lists to be
// created in the format native to the underlying graphics library.
// The caching works like OpenGL display lists.
//
// To create a display list:
//
// <ol>
// <li> Call the function newList() which will return a list id.  You need to
//      store the returned id somewhere so that it may be recalled later.
// <li> Perform some drawing commands.  These commands are output-only commands
//      that change the state of the PixelCanvas or draw some graphics or other
//      function that affects the canvas.
// <li> Call the function endList()
// </ol>
//
// To recall the drawing commands:
//
// <ol>
// <li> Call drawList(), passing the list id as the parameter
// </ol>
//
// To delete the list, call deleteList(), with the id
//
// The PixelCanvas maintains a translation stack which may be driven by
// calls to translate and calls to pushMatrix, popMatrix.
//
// The translation stack is an effective way to draw the same graphic in different
// places:
// <srcblock>
//
// uInt myGraphic = newList();
// ...
// endList();
// Matrix m(n,2);
// for (uInt i = 0; i < n; i++)
//   {
//     pc->pushMatrix();
//     pc->translate(m(i,0), m(i,1));
//     pc->drawList(myGraphic);
//     pc->popMatrix();
//   }
//
// </srcblock>
//
// Images are most correctly drawn through the following sequence of operations
//
// <ol>
// <li> Obtain the size of the current colormap with getColormapSize()
// <li> scale your data to fit in the range of [0,size-1];
// <li> call mapToColor() to get a proper color image (which you may consider
//      saving).
// <li> call drawImage()
// </ol>
//
// You may find that a class derived from
// <linkto class="WCDataScaleHandler">WCDataScaleHandler</linkto>, such as
// <linkto class="WCLinearScaleHandler">WCLinearScaleHandler</linkto>
// may be useful in step #2 above.
//
// mapToColor is also useful for transforming values that are associated with
// vector graphics as well (e.g., contour lines).
//
//
// The PixelCanvas layer is quite thin.  Most functionality is implemented
// in the derived classes.
//
// </synopsis>
//
// <motivation>
// Want a generic interface to possibly a variety of graphics hardware types.
// Want base class to maintain callback lists
// </motivation>
//
// <example>
// see the Display test directory
// </example>
//

        class PixelCanvas {
        public:
                virtual ~PixelCanvas();

                // add event handlers
                // <group>
                void addRefreshEventHandler(const PCRefreshEH &eh);
                void addMotionEventHandler(const PCMotionEH &eh);
                void addPositionEventHandler(const PCPositionEH &eh);
                // </group>

                // remove event handlers
                // <group>
                void removeRefreshEventHandler(const PCRefreshEH &eh);
                void removeMotionEventHandler(const PCMotionEH &eh);
                void removePositionEventHandler(const PCPositionEH &eh);
                // </group>

                // call event handlers
                // <group>
                void callRefreshEventHandlers(Display::RefreshReason reason);
                void callMotionEventHandlers(Int x, Int y, uInt state);
                void callPositionEventHandlers(Display::KeySym keysym, Bool keystate,
                                               Int x, Int y, uInt state);
                // </group>

                // enabling/disabling of event tracking
                // <group>
                virtual void enableMotionEvents() = 0;
                virtual void disableMotionEvents() = 0;
                virtual void enablePositionEvents() = 0;
                virtual void disablePositionEvents() = 0;
                // </group>

                // Does this canvas support cached display lists?  The user of the
                // canvas should always check this, because undefined behaviour can
                // result when an attempt is made to use a list on a PixelCanvas
                // which does not support lists.
                virtual Bool supportsLists() = 0;

                // begin caching display commands - return list ID
                virtual uInt newList() = 0;
                // end caching display commands
                virtual void endList() = 0;
                // (Cacheable) recall cached display commands
                virtual void drawList(uInt list) = 0;
                // translate all lists
                virtual void translateAllLists(Int xt, Int yt) = 0;
                // translate the list
                virtual void translateList(uInt list, Int xt, Int yt) = 0;
                // remove list from cache
                virtual void deleteList(uInt list) = 0;
                // flush all lists from the cache
                virtual void deleteLists() = 0;
                // return True if the list exists
                virtual Bool validList(uInt list) = 0;

                // (Cacheable) Set the font to the recognizable font name
                virtual Bool setFont(const String &fontName) = 0;

                // TODO: These should become abstract
                // Set the font via the DisplayLibrary Font class
                virtual Bool setFont(DLFont* /*font*/) {
                        return False;
                }

                // Set the font to font name / size
                virtual Bool setFont(const String& /*fontName*/, const Int /*fontSize*/) {
                        return False;
                }

                // (Cacheable) Draw text using that font aligned in some way to the
                // position
                virtual void drawText(Int x, Int y, const String &text,
                                      Display::TextAlign alignment = Display::AlignCenter) = 0;

                // TODO This should become abstract - NYI in GLPixelCanvas currently
                // Draw text at a specified angle.
                virtual void drawText(Int /*x*/, Int /*y*/, const String &/*text*/,
                                      const Float& /*angle*/,
                                      Display::TextAlign /*alignment*/ = Display::AlignCenter)
                { }

                // TODO : This should become abstract
                // Determine the width / height of a string of text based on
                // current settings.
                // <group>
                virtual Int textWidth(const String& /*text*/) {
                        return -1;
                }
                virtual Int textHeight(const String& /*text*/) {
                        return -1;
                }
                // </group>

                // (Cacheable) Draw an array of 2D color data as a raster image for zoom = <1,1>
                // <group>
                virtual void drawImage(const Matrix<uInt> &data, Int x, Int y) = 0;
                virtual void drawImage(const Matrix<Int> &data, Int x, Int y) = 0;
                virtual void drawImage(const Matrix<uLong> &data, Int x, Int y) = 0;
                virtual void drawImage(const Matrix<Float> &data, Int x, Int y) = 0;
                virtual void drawImage(const Matrix<Double> &data, Int x, Int y) = 0;
                // </group>

                // (Cacheable) Draw an array of 2D color data as a raster image,
                // taking note of the <src>Bool</src> mask.
                // Set opaqueMask to True to draw masked pixels in the background color;
                // otherwise they will be transparent (letting whatever was drawn
                // previously at that point show through).
                // <group>
                virtual void drawImage(const Int &/*x*/, const Int &/*y*/,
                                       const Matrix<uInt> &/*data*/,
                                       const Matrix<Bool> &/*mask*/,
                                       Bool /*opaqueMask*/=False) {
                        return;
                }
                // </group>

                // (Cacheable) Draw an array of 2D color data as a raster image for any positive integer zoom
                // <group>
                virtual void drawImage(const Matrix<uInt> &data, Int x, Int y,
                                       uInt xzoom, uInt yzoom) = 0;
                virtual void drawImage(const Matrix<Int> &data, Int x, Int y,
                                       uInt xzoom, uInt yzoom) = 0;
                virtual void drawImage(const Matrix<uLong> &data, Int x, Int y,
                                       uInt xzoom, uInt yzoom) = 0;
                virtual void drawImage(const Matrix<Float> &data, Int x, Int y,
                                       uInt xzoom, uInt yzoom) = 0;
                virtual void drawImage(const Matrix<Double> &data, Int x, Int y,
                                       uInt xzoom, uInt yzoom) = 0;
                // </group>

                // (Cacheable) Draw a component of a multi-channel image, storing it
                // in buffers until flushComponentImages() is called.
                virtual void drawImage(const Matrix<uInt> &data, const Int &x, const Int &y,
                                       const Display::ColorComponent &colorcomponent) = 0;

                // Fill one of the channel buffers.
                virtual void bufferComponent(const Matrix<uInt> &data,
                                             const Int &x, const Int &y,
                                             const Display::ColorComponent
                                             &colorcomponent) = 0;

                // (NOT CACHEABLE!) Flush the component buffers.
                virtual void flushComponentBuffers() = 0;

                // (Cacheable) Draw a single point using current color
                // <group>
                virtual void drawPoint(Int x1, Int y1) = 0;
                virtual void drawPoint(Float x1, Float y1) = 0;
                virtual void drawPoint(Double x1, Double y1) = 0;
                // </group>

                // (Cacheable) Draw N points specified as a Nx2 matrix
                // <group>
                virtual void drawPoints(const Matrix<Int> &verts) = 0;
                virtual void drawPoints(const Matrix<Float> &verts) = 0;
                virtual void drawPoints(const Matrix<Double> &verts) = 0;
                // </group>

                // (Cacheable) Draw a bunch of points using current color
                // <group>
                virtual void drawPoints(const Vector<Int> &x1, const Vector<Int> &y1) = 0;
                virtual void drawPoints(const Vector<Float> &x1,
                                        const Vector<Float> &y1) = 0;
                virtual void drawPoints(const Vector<Double> &x1,
                                        const Vector<Double> &y1) = 0;
                // </group>

                // (Cacheable) Draw a single line using current color
                // <group>
                virtual void drawLine(Int x1, Int y1, Int x2, Int y2) = 0;
                virtual void drawLine(Float x1, Float y1, Float x2, Float y2) = 0;
                virtual void drawLine(Double x1, Double y1, Double x2, Double y2) = 0;
                // </group>

                // (Cacheable) Draw N/2 lines from an Nx2 matrix
                // <group>
                virtual void drawLines(const Matrix<Int> &verts) = 0;
                virtual void drawLines(const Matrix<Float> &verts) = 0;
                virtual void drawLines(const Matrix<Double> &verts) = 0;
                // </group>

                // (Cacheable) Draw a bunch of unrelated lines using current color
                // <group>
                virtual void drawLines(const Vector<Int> &x1, const Vector<Int> &y1,
                                       const Vector<Int> &x2, const Vector<Int> &y2) = 0;
                virtual void drawLines(const Vector<Float> &x1, const Vector<Float> &y1,
                                       const Vector<Float> &x2,
                                       const Vector<Float> &y2) = 0;
                virtual void drawLines(const Vector<Double> &x1, const Vector<Double> &y1,
                                       const Vector<Double> &x2,
                                       const Vector<Double> &y2) = 0;
                // </group>

                // (Cacheable) Draw a single connected line between the points given
                // <group>
                virtual void drawPolyline(const Vector<Int> &x1,
                                          const Vector<Int> &y1) = 0;
                virtual void drawPolyline(const Vector<Float> &x1,
                                          const Vector<Float> &y1) = 0;
                virtual void drawPolyline(const Vector<Double> &x1,
                                          const Vector<Double> &y1) = 0;
                // </group>

                // (Cacheable) Draw N-1 connected lines from Nx2 matrix of vertices
                // <group>
                virtual void drawPolyline(const Matrix<Int> &verts) = 0;
                virtual void drawPolyline(const Matrix<Float> &verts) = 0;
                virtual void drawPolyline(const Matrix<Double> &verts) = 0;
                // </group>

                // Draw a "marker". See <linkto class="Display">Display</linkto>
                // for a list of available markers.
                // <group>
                virtual void drawMarker(const Int& x1, const Int& y1,
                                        const Display::Marker& marker,
                                        const Int& pixelHeight);
                virtual void drawMarker(const Float& x1, const Float& y1,
                                        const Display::Marker& marker,
                                        const Int& pixelHeight);
                virtual void drawMarker(const Double& x1, const Double& y1,
                                        const Display::Marker& marker,
                                        const Int& pixelHeight);
                // </group>

                // (Cacheable) Draw a closed polygon
                // <group>
                virtual void drawPolygon(const Vector<Int> &x1, const Vector<Int> &y1) = 0;
                virtual void drawPolygon(const Vector<Float> &x1,
                                         const Vector<Float> &y1) = 0;
                virtual void drawPolygon(const Vector<Double> &x1,
                                         const Vector<Double> &y1) = 0;
                // </group>

                // (Cacheable) Draw and fill a closed polygon
                // <group>
                virtual void drawFilledPolygon(const Vector<Int> &x1,
                                               const Vector<Int> &y1) = 0;
                virtual void drawFilledPolygon(const Vector<Float> &x1,
                                               const Vector<Float> &y1) = 0;
                virtual void drawFilledPolygon(const Vector<Double> &x1,
                                               const Vector<Double> &y1) = 0;
                // </group>

                // (Cacheable) Draw a closed N-sided polygon from Nx2 matrix of vertices
                // <group>
                virtual void drawPolygon(const Matrix<Int> &verts) = 0;
                virtual void drawPolygon(const Matrix<Float> &verts) = 0;
                virtual void drawPolygon(const Matrix<Double> &verts) = 0;
                // </group>

                // (Cacheable) Draw a rectangle
                // <group>
                virtual void drawRectangle(Int x1, Int y1, Int x2, Int y2) = 0;
                virtual void drawRectangle(Float x1, Float y1, Float x2, Float y2) = 0;
                virtual void drawRectangle(Double x1, Double y1, Double x2, Double y2) = 0;
                // </group>

                // (Cacheable) Draw a filled rectangle
                // <group>
                virtual void drawFilledRectangle(Int x1, Int y1, Int x2, Int y2) = 0;
                virtual void drawFilledRectangle(Float x1, Float y1, Float x2, Float y2) = 0;
                virtual void drawFilledRectangle(Double x1, Double y1, Double x2,
                                                 Double y2) = 0;
                // </group>

                // (Cacheable) Draw a set of points, specifying a color per point to be drawn.
                // <group>
                virtual void drawColoredPoints(const Vector<Int> &x1,
                                               const Vector<Int> &y1,
                                               const Vector<uInt> &colors) = 0;
                virtual void drawColoredPoints(const Vector<Float> &x1,
                                               const Vector<Float> &y1,
                                               const Vector<uInt> &colors) = 0;
                virtual void drawColoredPoints(const Vector<Double> &x1,
                                               const Vector<Double> &y1,
                                               const Vector<uInt> &colors) = 0;
                virtual void drawColoredPoints(const Matrix<Int> &xy,
                                               const Vector<uInt> &colors) {
                        drawColoredPoints(xy.column(0), xy.column(1), colors);
                }
                virtual void drawColoredPoints(const Matrix<Float> &xy,
                                               const Vector<uInt> &colors) {
                        drawColoredPoints(xy.column(0), xy.column(1), colors);
                }
                virtual void drawColoredPoints(const Matrix<Double> &xy,
                                               const Vector<uInt> &colors) {
                        drawColoredPoints(xy.column(0), xy.column(1), colors);
                }
                // </group>

                // (Cacheable) Draw a set of lines, specifying a color per line to be drawn.
                // <group>
                virtual void drawColoredLines(const Vector<Int> &x1,
                                              const Vector<Int> &y1,
                                              const Vector<Int> &x2,
                                              const Vector<Int> &y2,
                                              const Vector<uInt> &colors) = 0;
                virtual void drawColoredLines(const Vector<Float> &x1,
                                              const Vector<Float> &y1,
                                              const Vector<Float> &x2,
                                              const Vector<Float> &y2,
                                              const Vector<uInt> &colors) = 0;
                virtual void drawColoredLines(const Vector<Double> &x1,
                                              const Vector<Double> &y1,
                                              const Vector<Double> &x2,
                                              const Vector<Double> &y2,
                                              const Vector<uInt> &colors) = 0;
                // </group>

                // Draw a single ellipse using the current pen (ie. color,
                // thickness, style).  The x and y location must be given, along
                // with the semi-major and -minor axis lengths, and the position
                // angle measured in degrees positive from the x axis in a
                // counter-clockwise direction. If outline is False, the
                // ellipse is solid filled, else it is just outlined.
                // xstretch, ystretch should be left defaulted to 1 in most cases;
                // see usage example in WorldCanvas::drawBeamEllipse(), where they are
                // used to stretch a beam ellipse when the display is also linearly
                // stretched away from the aspect ratio natural to the sky projection.
                // They multiply the relative x and y screen coordinates of ellipse
                // points, _before_ they are added to cx and cy.  xstretch, ystretch
                // can be negative (though smajor, sminor normally would not be).
                virtual void drawEllipse(const Float &cx, const Float &cy,
                                         const Float &smajor, const Float &sminor,
                                         const Float &pangle, Bool outline = True,
                                         Float xstretch = 1., Float ystretch = 1.);

                // Draw a set of colored ellipses, possibly with borders.  The x and
                // y locations must given, along with semi-major and semi-minor
                // axes, and position angle measured in degrees positive from the x
                // axis in a counter-clockwise direction.  The size of the ellipses
                // is globally scaled by the scale factor, and if <src>outline</src>
                // is <src>True</src>, then each ellipse will have an outline in the
                // current pen color.  <group>
                virtual void drawColoredEllipses(const Matrix<Float> &centres,
                                                 const Vector<Float> &smajor,
                                                 const Vector<Float> &sminor,
                                                 const Vector<Float> &pangle,
                                                 const Vector<uInt> &colors,
                                                 const Float &scale = 1.0,
                                                 const Bool &outline = True);
                // </group>

                // vector primitive buffering
                /*
                void bufferPoint(Int x, Int y)
                  { vgbuf_.accumPoint(x,y); }
                void bufferLine(Int x1, Int y1, Int x2, Int y2)
                  { vgbuf_.accumLine(x1,y1,x2,y2); }
                void bufferPolylinePoint(Int x, Int y)
                  { vgbuf_.accumPolylinePoint(x,y); }
                void bufferPolygonPoint(Int x, Int y)
                  { vgbuf_.accumPolygonPoint(x,y); }
                */
                void bufferPoint(Float x, Float y) {
                        vgbuf_.accumPoint(x,y);
                }
                void bufferLine(Float x1, Float y1, Float x2, Float y2) {
                        vgbuf_.accumLine(x1,y1,x2,y2);
                }
                void bufferPolylinePoint(Float x, Float y) {
                        vgbuf_.accumPolylinePoint(x,y);
                }
                void bufferPolygonPoint(Float x, Float y) {
                        vgbuf_.accumPolygonPoint(x,y);
                }
                void flushBuffer() {
                        vgbuf_.flush();
                }

                // Set Graphics Attributes
                // Options for functions with enum argument
                // listed in <linkto class=Display>DisplayEnums</linkto>
                // <group>
                virtual void setDrawFunction(Display::DrawFunction function) = 0;
                virtual void setForeground(uLong color) = 0;
                virtual void setBackground(uLong color) = 0;
                //virtual void setLineWidth(uInt width) = 0;
                virtual void setLineWidth(Float width) = 0;
                virtual void setLineStyle(Display::LineStyle style) = 0;
                virtual void setCapStyle(Display::CapStyle style) = 0;
                virtual void setJoinStyle(Display::JoinStyle style) = 0;
                virtual void setFillStyle(Display::FillStyle style) = 0;
                virtual void setFillRule(Display::FillRule rule) = 0;
                virtual void setArcMode(Display::ArcMode mode) = 0;
                // </group>

                // Get Graphics Attributes
                // <group>
                virtual Display::DrawFunction getDrawFunction() const = 0;
                virtual uLong                 getForeground()   const = 0;
                virtual uLong                 getBackground()   const = 0;
                //virtual uInt                  getLineWidth()    const = 0;
                virtual Float                 getLineWidth()    const = 0;
                virtual Display::LineStyle    getLineStyle()    const = 0;
                virtual Display::CapStyle     getCapStyle()     const = 0;
                virtual Display::JoinStyle    getJoinStyle()    const = 0;
                virtual Display::FillStyle    getFillStyle()    const = 0;
                virtual Display::FillRule     getFillRule()     const = 0;
                virtual Display::ArcMode      getArcMode()      const = 0;
                // </group>

                // (Cacheable) Option Control
                // Options listed in <linkto class=Display>DisplayEnums</linkto>
                // <group>
                virtual Bool enable(Display::Option option) = 0;
                virtual Bool disable(Display::Option option) = 0;
                // </group>

                // Control the image-caching strategy
                virtual void setImageCacheStrategy(Display::ImageCacheStrategy strategy) = 0;
                virtual Display::ImageCacheStrategy imageCacheStrategy() const = 0;

                // (Cacheable) Setup the clip window.  The clip window, when enabled, allows
                // a user to clip all graphics output to a rectangular region on
                // the screen.
                // <group>
                virtual void setClipWindow(Int x1, Int y1, Int x2, Int y2) = 0;
                virtual void getClipWindow(Int &x1, Int &y1, Int &x2, Int &y2) = 0;
                // </group>

                // (Not Cacheable) Redraw the window
                // <group>
                void redraw() {
                        refresh();
                }
                virtual void refresh(const Display::RefreshReason &reason =
                                         Display::UserCommand,
                                     const Bool &explicitrequest = True) = 0;
                // </group>

                // Cause display to flush any graphics commands not yet drawn
                virtual void flush() = 0;

                // (Cacheable) Clear the window using the background color
                // <group>
                virtual void clear() = 0;
                virtual void clear(Int x1, Int y1, Int x2, Int y2) = 0;
                // </group>

                // (Cacheable) Set the color to use for clearing the display
                // <group>
                virtual void setClearColor(uInt colorIndex) = 0;
                virtual void setClearColor(const String &colorname) = 0;
                virtual void setClearColor(float r, float g, float b) = 0;
                // </group>

                // (Not Cacheable) Get the current color to use for clearing the display.
                virtual uInt clearColor() const = 0;
                virtual void getClearColor(float &r, float &g, float &b) const = 0;

                // Get/set the current foreground/background colors.  These colors
                // should be used when the special Strings "foreground" and "background"
                // are given for a color.
                // <group>
                virtual void setDeviceForegroundColor(const String colorname) = 0;
                virtual String deviceForegroundColor() const = 0;
                virtual void setDeviceBackgroundColor(const String colorname) = 0;
                virtual String deviceBackgroundColor() const = 0;
                // </group>

                // Return the width of the PixelCanvas in pixels
                virtual uInt width() const = 0;
                // Return the height of the PixelCanvas in pixels
                virtual uInt height() const = 0;
                // Return the depth of the PixelCanvas in bits
                virtual uInt depth() const = 0;
                // Get the pixel density (in dots per inch [dpi]) of the PixelCanvas
                virtual void pixelDensity(Float &xdpi, Float &ydpi) const = 0;

                // (Cacheable) Set current color (works in RGB or colormap mode)
                // <group>
                virtual void setColor(uInt colorIndex) = 0;
                virtual void setColor(const String &colorname) = 0;
                virtual void setRGBColor(float r, float g, float b) = 0;
                virtual void setHSVColor(float h, float s, float v);
                // </group>

                // Get color components in range 0 to 1 without actually
                // allocating the color.  This is needed to set up other
                // devices, for example PgPlot.
                virtual Bool getColorComponents(const String &colorname, Float &r,
                                                Float &g, Float &b) = 0;

                // (Not Cacheable) Returns the current color as a color index
                virtual uInt color() const = 0;

                // (Not Cacheable) Retuns the current color as an RGB triple
                virtual void getColor(float &r, float &g, float &b) const = 0;

                // (Not Cacheable) Get color index value (works in RGB or colormap mode)
                // <group>
                virtual Bool getColor(Int x, Int y, uInt &color) = 0;
                virtual Bool getRGBColor(Int x, Int y, float &r, float &g, float &b) = 0;
                virtual Bool getHSVColor(Int x, Int y, float &h, float &s, float &v);
                // </group>

                // (Not Cacheable) resize request.  returns true if window was resized.
                // Will refresh if doCallbacks is True.
                //#dk virtual Bool resize(uInt reqXSize, uInt reqYSize, Bool doCallbacks = True) = 0;
                virtual Bool resize(uInt /*reqXSize*/, uInt /*reqYSize*/, Bool /*doCallbacks*/ = True) {
                        return False;
                }

                // (Not Cacheable) resize the colortable by requesting a new number of cells
                virtual Bool resizeColorTable(uInt newSize) = 0;

                // (Not Cacheable) resize the colortable by requesting a new RGB/HSV cube
                virtual Bool resizeColorTable(uInt nReds, uInt nGreens, uInt nBlues) = 0;

                // Need a mechanism to return the PixelCanvasColorTable so
                // drawing functions within classes can operate.
                virtual PixelCanvasColorTable * pcctbl() const = 0;

                virtual void setPcctbl(PixelCanvasColorTable * pcctbl) = 0;

                // (Not Cacheable) set/get the current colormap.  Undefined behavior results from
                // setting the colormap to a map that is not registered.  This cannot be cached
                // because it affects the result of getColormapSize().  Remember that once data
                // is mapped with mapToColor, it is no longer important to worry about which
                // colormap is active for purposes of drawing the image or vectors.
                // colormapRegistered() can be used to determine whether the currently set
                // colormap() is indeed registered/installed (i.e., color cells have been
                // allocated within the pcctbl).
                // <group>
                void setColormap(Colormap * map);
                Colormap * colormap() const {
                        return colormap_;
                }
                Bool colormapRegistered() {
                        return pcctbl()->member(colormap_);
                }
                // </group>

                // register a colormap to the pixelcanvas.  Registration counts are
                // remembered, so that map A is guaranteed to be available as long as
                // the number of register(A)'s exceed the number of unregister(A)'s.
                // Requests are forwarded to the PixelCanvas' PixelCanvasColorTable.
                void registerColormap(Colormap * dcmap, Float weight = 1.0);

                // Register the <src>cmap</src> Colormap on the PixelCanvas,
                // replacing the <src>cmapToReplace</src> Colormap if possible.
                void registerColormap(Colormap *cmap, Colormap *cmapToReplace);

                // unregister a colormap from a pixelcanvas.  Unregistering the
                // current map may result in undefined behavior.
                void unregisterColormap(Colormap * dcmap);

                // return the size of the current colormap
                uInt getColormapSize() const {
                        return pcctbl()->getColormapSize(colormap_);
                }

                // map [0,N-1] into colorpixels, where N is the current colormap size
                // The values are returned as unsigned integers in their respective
                // array.
                // <note role="tip">The choice of what type to use should be guided by
                // the number of graphics bitplanes available.  For most systems with
                // 8-bit color, uChar is optimal.  Some systems with 12 bits per pixel
                // with an alpha channel may require using the uLong. </note>
                //
                // <note role="warning">uChar type may not have enough bits
                // to hold the pixel index on some high-end graphics systems </note>
                // <note role="warning">uShort type may not have enough bits
                // to hold the pixel index on some high-end graphics systems </note>
                // <group>

                void mapToColor(Array<uChar> &outArray,
                                const Array<uChar> &inArray, Bool rangeCheck = False) {
                        pcctbl()->mapToColor(colormap_, outArray, inArray, rangeCheck);
                }
                void mapToColor(Array<uShort> &outArray,
                                const Array<uShort> &inArray, Bool rangeCheck = False) {
                        pcctbl()->mapToColor(colormap_, outArray, inArray, rangeCheck);
                }
                void mapToColor(Array<uInt> &outArray,
                                const Array<uInt> &inArray, Bool rangeCheck = False) {
                        pcctbl()->mapToColor(colormap_, outArray, inArray, rangeCheck);
                }
                void mapToColor(Array<uLong> &outArray,
                                const Array<uLong> &inArray, Bool rangeCheck = False) {
                        pcctbl()->mapToColor(colormap_, outArray, inArray, rangeCheck);
                }
                // </group>

                // same as above except the matrix is operated on in place.  Only unsigned
                // values make sense here.
                // <group>
                void mapToColor(Array<uChar> &inOutArray, Bool rangeCheck = False) {
                        pcctbl()->mapToColor(colormap_, inOutArray, rangeCheck);
                }
                void mapToColor(Array<uShort> &inOutArray, Bool rangeCheck = False) {
                        pcctbl()->mapToColor(colormap_, inOutArray, rangeCheck);
                }
                void mapToColor(Array<uInt> &inOutArray, Bool rangeCheck = False) {
                        pcctbl()->mapToColor(colormap_, inOutArray, rangeCheck);
                }
                void mapToColor(Array<uLong> &inOutArray, Bool rangeCheck = False) {
                        pcctbl()->mapToColor(colormap_, inOutArray, rangeCheck);
                }
                // </group>



                void mapToColor(Array<uInt> &outArray,
                                const Array<uInt> &inArrayRed, const Array<uInt> &inArrayGreen, const Array<uInt>& inArrayBlue) {
                        pcctbl()->mapToColorRGB(colormap_, outArray, inArrayRed, inArrayGreen, inArrayBlue);
                }


                // Multi-Channel functions that combine separate array channels into
                // a single array of output colors for use with functions that take
                // color values.
                // These two functions accept color values from [0-1] for each channel.
                // The colorModel is compared with the model of the PixelCanvasColorTable
                // and is used to perform the correct mapping.
                // <group>
                void mapToColor3(Array<uLong> &out,
                                 const Array<Float> &chan1in,
                                 const Array<Float> &chan2in,
                                 const Array<Float> &chan3in);
                void mapToColor3(Array<uLong> &out,
                                 const Array<Double> &chan1in,
                                 const Array<Double> &chan2in,
                                 const Array<Double> &chan3in);
                // </group>

                // This one maps values between 0 and the integer maximum value for
                // each channel into a single output image suitable for
                // PixelCanvas::drawImage.
                // <group>
                virtual void mapToColor3(Array<uLong> &out,
                                         const Array<uInt> &chan1in,
                                         const Array<uInt> &chan2in,
                                         const Array<uInt> &chan3in);
                // </group>


                // save/restore the current translation.  This is called pushMatrix because
                // eventually we may want scaling or rotation to play a modest
                // role here.
                // <group>
                virtual void pushMatrix() = 0;
                virtual void popMatrix() = 0;
                // </group>
                // zero the current translation
                virtual void loadIdentity() = 0;

                // translation functions
                // translate applies a relative translation to the current matrix and
                // can be used to position graphics.  Together with pushMatrix and
                // popMatrix it can be used to build heirarchical scenes.
                // <group>
                virtual void translate(Int xt, Int yt) = 0;
                virtual void getTranslation(Int &xt, Int &yt) const = 0;
                virtual Int xTranslation() const = 0;
                virtual Int yTranslation() const = 0;
                // </group>

                // return the drawing buffer, the target destination for graphics
                Display::DrawBuffer drawBuffer() const {
                        return drawBuffer_;
                }
                // (Not cacheable) set the draw buffer
                virtual void setDrawBuffer(Display::DrawBuffer buf) = 0;
                // buffer memory exchanges
                // (Not cacheable)
                // <group>
                virtual void copyBackBufferToFrontBuffer() = 0;
                virtual void copyFrontBufferToBackBuffer() = 0;
                virtual void swapBuffers() = 0;
                // </group>

                // partial buffer memory exchanges.  (x1,y1 are blc, x2,y2 are trc)
                // <group>
                virtual void copyBackBufferToFrontBuffer(Int x1, Int y1, Int x2, Int y2) = 0;
                virtual void copyFrontBufferToBackBuffer(Int x1, Int y1, Int x2, Int y2) = 0;
                virtual void swapBuffers(Int x1, Int y1, Int x2, Int y2) = 0;
                // </group>

                // return the drawmode (Compile or Draw)
                // Compile drawmode means that a display list is currently being built
                // Draw drawmode means that drawing commands are not cached but
                // instead are sent to the display.  This command is controlled by
                // the caching state using newList()
                Display::DrawMode drawMode() const {
                        return drawMode_;
                }

                // return the colorModel used for multichannel color
                Display::ColorModel colorModel() const {
                        return colorModel_;
                }
                // Set the input color model for multichannel color
                void setColorModel(Display::ColorModel colorModel);


                // return True if the refresh is active (Added for X11PixelCanvas DefaultBuffer)
                Bool refreshActive() const {
                        return refreshActive_;
                }

                // return True if refresh is allowed right now...
                virtual Bool refreshAllowed() const {
                        return True;
                }

                virtual Float pixelScaling() const {
                        return 1.0;
                }

        protected:

                // Abstract base class idiom
                PixelCanvas();
                PixelCanvas( const PixelCanvas * );
                PixelCanvas(PixelCanvasColorTable * pcctbl);

                // Only allowed by derived classes
                void setDrawMode(Display::DrawMode mode) {
                        drawMode_ = mode;
                }

                // Also allowed only by derived classes
                void setDrawBuffer_(Display::DrawBuffer buf) {
                        drawBuffer_ = buf;
                }

                // True if the PixelCanvas was the one who
                // registered the existing colortable
                Bool defaultColormapActive_;

        private:
                Matrix<Float> getMarker(const Display::Marker& marker, const Float& pixelHeight);

                // This is the current colormap.
                Colormap * colormap_;


                // This is the current drawing mode
                Display::DrawMode drawMode_;

                // The current drawing buffer
                Display::DrawBuffer drawBuffer_;

                // The current color cube model to be used for all
                // multichannel color mapping.
                Display::ColorModel colorModel_;

                // True if refresh is active
                Bool refreshActive_;

                // Number of colormaps registered by external clients
                uInt nRegisteredColormaps_;

                // This is the list of registered refresh EventHandlers
                List<void *> refreshEHList_;
                // This is the list of registered motion EventHandlers
                List<void *> motionEHList_;
                // This is the list of registered position EventHandlers
                List<void *> positionEHList_;

                // The PCVGBuffer is used to accumulate lines and points until
                // flushed (or the buffer is full)
                PCVGBuffer vgbuf_;
        };


} //# NAMESPACE CASA - END

#endif