Main Page   Class Hierarchy   Compound List   File List   Compound Members   File Members

Display.h

Go to the documentation of this file.
00001 /*********************************************************************************
00002  *
00003  * Razor! Engine - A modular C++ presentation engine
00004  *
00005  * $Id: Display.h,v 1.4 2003/05/30 12:30:21 teacy Exp $
00006  *
00007  * Copyright (c) 2000-2003 Tilo Christ. All Rights Reserved.
00008  * 
00009  * Permission is hereby granted, free of charge, to any person obtaining a 
00010  * copy of this software and associated documentation files (the  "Software"), 
00011  * to deal in the Software without restriction, including without limitation 
00012  * the rights to use, copy, modify, merge, publish, distribute, sublicense, 
00013  * and/or sell copies of the Software, and to permit persons to whom the Software 
00014  * is furnished to do so, subject to the following conditions:
00015  *
00016  * The above copyright notice and this permission notice shall be included in all 
00017  * copies or substantial portions of the Software.
00018  *
00019  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
00020  * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 
00021  * PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE 
00022  * FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 
00023  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00024  *
00025  **********************************************************************************/
00026 
00027 /*
00028  TODO: 
00029     - Should most of Display be made private and be declared as a friend of Presentation?
00030  */
00031 
00032 
00033 #ifndef DISPLAY_H
00034 #define DISPLAY_H
00035 
00036 #include <PalmOS.h>
00037 #include "RazorSections.h"
00038 #include "gfx/Canvas.h"
00039 
00040 
00041 /**
00042  * The properties of the display.
00043  * Used to communicate required display properties from the Screens to the Display.
00044  */
00045 struct DisplayProperties
00046 {
00047     /**
00048      * The coordinate system.
00049      * This coordinate system will be used for all coordinate calculations on all canvases.
00050      */
00051     Canvas::CoordSystem coordSystem;
00052     /**
00053      * Display property flags.
00054      * This is reserved for future use.
00055      * TODO: Turn this into a bitfield? Gather ideas for flags.
00056      */
00057     UInt16 flags;
00058 };
00059 
00060 
00061 /**
00062  * The properties of the viewport.
00063  * Used to communicate viewport properties from the Screens to the Display.
00064  */
00065 struct ViewportProperties
00066 {
00067     /**
00068      * The size and position of the viewport.
00069      * All coordinates are in logical units.
00070      */
00071     RectangleType region;
00072 };
00073 
00074 
00075 /**
00076  * The device's physical display area. It provides access to
00077  * the physical properties of the area (dimensions, color), and it provides access
00078  * to the display canvas and the viewport canvas for drawing. It manages the double-buffering
00079  * functionality for flicker-free drawing.
00080  * <br>
00081  * It also enables the framework to setup the physical display. This functionality
00082  * is not directly accessible.
00083  */
00084 class Display
00085 {
00086     public:
00087     /**
00088      * Constants to express the display density.
00089      */
00090     enum Density {DENSITY_SINGLE = 1, /**< a single density display, used by lores devices */
00091                   DENSITY_DOUBLE = 2  /**< a double density display, used by hires devices */
00092                  };
00093 
00094 
00095 ///@name Construction / Destruction
00096 //@{
00097     /**
00098      * Construct a new Display.
00099      */
00100     Display() SEC_RAZOR_INIT;
00101 
00102     /**
00103      * Destroy the Display.
00104      */
00105     virtual ~Display() SEC_RAZOR_INIT;
00106     void destroy() SEC_RAZOR_INIT;
00107 //@}
00108 
00109 /// @name Output management
00110 //@{
00111     /**
00112      * Begin drawing into the offscreen viewport
00113      */
00114     void beginDrawViewport();
00115     
00116     /**
00117      * End drawing into the offscreen viewport
00118      * 
00119      * @param dirtyRectangle the area that was modified by the viewport draw operations.
00120      *               NULL means the entire viewport is dirty.
00121      */
00122     virtual void endDrawViewport(RectangleType *dirtyRectangle);
00123 
00124     /**
00125      * Display offscreen viewport
00126      */
00127     virtual void showViewport() = 0;    
00128 
00129     /**
00130      * Capture the display for use with Razor!
00131      */
00132     virtual void captureDisplay() SEC_RAZOR_INIT = 0;
00133 
00134     /**
00135      * Release the display from use by Razor!
00136      * Make it usable by the OS again.
00137      */
00138     virtual void releaseDisplay() SEC_RAZOR_INIT = 0;
00139 //@}
00140 
00141 /// @name Physical Display management
00142 //@{
00143     virtual void initDisplay(const DisplayProperties& displayProperties) SEC_RAZOR_INIT = 0;
00144     void initViewport(const ViewportProperties& viewport) SEC_RAZOR_INIT;
00145 //@}
00146 
00147 /// @name Canvas management
00148 //@{
00149     /**
00150      * Get the display canvas.
00151      */
00152     Canvas *getDisplayCanvas() const SEC_RAZOR;
00153 
00154     /**
00155      * Get the viewport canvas.
00156      */
00157     Canvas *getViewportCanvas() const SEC_RAZOR;
00158 //@}
00159 
00160     /**
00161      * The physical width (columns) of the display
00162      */
00163     static UInt16 cols;
00164 
00165     /**
00166      * The physical height (rows) of the display
00167      */
00168     static UInt16 rows;
00169 
00170     /**
00171      * The depth of the display in bpp.
00172      */
00173     static UInt32 depth;
00174 
00175     /**
00176      * The density of the display as a Density enumeration member.
00177      */
00178     static Density density;
00179     
00180     /**
00181      * Is this a color display?
00182      */
00183     static Boolean colorMode;
00184     
00185     /**
00186      * Is this a direct color (non-palettized) display?
00187      */
00188     static Boolean directColor;
00189 
00190     protected:  
00191     virtual void createViewportCanvas(const ViewportProperties& viewport) SEC_RAZOR_INIT = 0;
00192     
00193 
00194     /**
00195      * Set the display back to normal
00196      */
00197     virtual void resetDisplay() SEC_RAZOR_INIT = 0;
00198 
00199 
00200     // Viewport
00201     ViewportProperties viewport;    
00202 
00203     // Canvases
00204     Canvas *displayCanvas;
00205     Canvas *viewportCanvas;
00206 
00207     // Dirty rectangle management
00208     // TODO: Should dirty rectangle management be made a task of the Canvas?
00209     RectangleType currentBounds;
00210     RectangleType lastBounds;
00211     RectangleType copyBounds;
00212 };
00213 
00214 #endif // DISPLAY_H

Razor! Engine Developer's Guide. Copyright © by Tilo Christ. All Rights Reserved. Last updated: 31 May 2003