Display.h

00001 /*
00002  *  Copyright 2014 Embedded Artists AB
00003  *
00004  *  Licensed under the Apache License, Version 2.0 (the "License");
00005  *  you may not use this file except in compliance with the License.
00006  *  You may obtain a copy of the License at
00007  *
00008  *    http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  *  Unless required by applicable law or agreed to in writing, software
00011  *  distributed under the License is distributed on an "AS IS" BASIS,
00012  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  *  See the License for the specific language governing permissions and
00014  *  limitations under the License.
00015  */
00016 
00017 #ifndef DISPLAY_H
00018 #define DISPLAY_H
00019 
00020 #include "mbed.h"
00021 #include "bios.h"
00022 
00023 /**
00024  * Display example
00025  *
00026  * @code
00027  * #include "mbed.h"
00028  * #include "DMBoard.h"
00029  *
00030  * int main(void) {
00031  *    // initialize the display
00032  *    DMBoard::instance().init();
00033  *
00034  *    // allocate one framebuffer
00035  *    Display* disp = DMBoard::instance().display();
00036  *    uint16_t* fb = (uint16_t*)disp->allocateFramebuffer();
00037  *    if (fb == NULL) {
00038  *      DMBoard::instance().logger()->printf("Failed to allocate memory for framebuffer\r\n");
00039  *      mbed_die();
00040  *    }
00041  *
00042  *    // draw something on the framebuffer
00043  *    ...
00044  *
00045  *    // turn on the display
00046  *    disperr = disp->powerUp(fb);
00047  *    if (disperr != Display::Ok) {
00048  *      DMBoard::instance().logger()->printf("Failed to initialize the display, got error %d\r\n", disperr);
00049  *      mbed_die();
00050  *    }
00051  *
00052  *    ...
00053  * }
00054  * @endcode
00055  */
00056 class Display {
00057 public:
00058     enum DisplayError {
00059         DisplayError_Ok                =   BiosError_Ok,
00060         DisplayError_ConfigError       =   BiosError_ConfigError,
00061         DisplayError_WrongBPP          =   BiosError_WrongBPP,
00062         DisplayError_InvalidParam      =   BiosError_InvalidParam,
00063         DisplayError_NoInit            =   BiosError_NoInit,
00064         DisplayError_CalibrationError  =   BiosError_Calibration,
00065         DisplayError_Timeout           =   BiosError_Timeout,
00066         DisplayError_TouchNotSupported =   BiosError_NotSupported,
00067         DisplayError_MemoryError,
00068     };
00069     
00070     enum Resolution {
00071         Resolution_16bit_rgb565 = Res_16bit_rgb565,
00072         Resolution_18bit_rgb666 = Res_18bit_rgb666,
00073         Resolution_24bit_rgb888 = Res_24bit_rgb888,
00074     };
00075     
00076     /** Turns the display on with the specified framebuffer showing
00077      *
00078      *  @param framebuffer  the data to show
00079      *  @param res          the resolution to use
00080      *  @param rate         the frame rate to use
00081      *
00082      *  @returns
00083      *       Ok on success
00084      *       An error code on failure
00085      */
00086     virtual DisplayError powerUp(void* framebuffer, Resolution res = Resolution_16bit_rgb565, FrameRate_t rate = FrameRate_Normal) = 0;
00087   
00088     /** Turns the display off
00089      *
00090      *  @returns
00091      *       Ok on success
00092      *       An error code on failure
00093      */
00094     virtual DisplayError powerDown() = 0;
00095   
00096     /** Sets the backlight level. 0% is off and 100% is fully on
00097      *
00098      *  @param percent   backlight in %
00099      *
00100      *  @returns
00101      *       Ok on success
00102      *       An error code on failure
00103      */
00104     virtual DisplayError backlight(int percent) = 0;
00105   
00106     /** Returns the width (in pixels) of the display
00107      *
00108      *  @returns the display width
00109      */
00110     virtual uint16_t width() = 0;
00111 
00112     /** Returns the height (in pixels) of the display
00113      *
00114      *  @returns the display height
00115      */
00116     virtual uint16_t height() = 0;
00117 
00118     /** Returns the number of bytes used by each pixel
00119      *
00120      *  @returns bytes per pixel
00121      */
00122     virtual uint16_t bytesPerPixel() = 0;
00123 
00124     /** Returns the number of bytes used for each frame buffer
00125      *
00126      *  @returns width*height*bytesPerPixel
00127      */
00128     virtual uint32_t fbSize() = 0;
00129 
00130     /** Returns the display orientation
00131      *
00132      *  @returns the display orientation
00133      */
00134     virtual bool landscape() = 0;
00135 
00136     /** Returns true if the specified resolution can be used
00137      *
00138      *  @returns true if supported, false if not
00139      */
00140     virtual bool isSupported(Resolution res) = 0;
00141 
00142     /** Returns the current resolution
00143      *
00144      *  @returns the current resolution
00145      */
00146     virtual Resolution currentResolution() = 0;
00147     
00148     /** Replaces the current framebuffer.
00149      *
00150      * Note that this requires the caller or someone else to have a
00151      * reference to the existing framebuffer, otherwise that memory
00152      * is lost.
00153      *
00154      *  @param buff the new framebuffer
00155      */
00156     virtual void setFramebuffer(void* buff) = 0;
00157     
00158     /** Replaces the current framebuffer with the specified one.
00159      *
00160      * This function as opposed to the setFramebuffer() one does return
00161      * the old framebuffer. This way the caller can save the old one and
00162      * then swap it back when done.
00163      *
00164      *  @param buff the new framebuffer
00165      *  @returns the old framebuffer
00166      */
00167     virtual void* swapFramebuffer(void* buff) = 0;
00168     
00169     /** Allocate enough memory for one framebuffer
00170      *
00171      * This function is a to make it easier to allocate memory for framebuffers
00172      * as the number of bytes needed depends on width, height and bytes per pixel.
00173      *
00174      * Free the allocated memory when done using the free() function.
00175      *
00176      *  @param res the resolution (default is the one that the display is using)
00177      *  @returns a new framebuffer or NULL if out of memory 
00178      */
00179     virtual void* allocateFramebuffer(Resolution res=Resolution_16bit_rgb565) = 0;
00180     
00181     /** Allocate enough memory for one or more consequtive framebuffers
00182      *
00183      * This function is a to make it easier to allocate memory for framebuffers
00184      * as the number of bytes needed depends on width, height and bytes per pixel.
00185      *
00186      * Free the allocated memory when done using the free() function.
00187      *
00188      * Use the default parameters to get one framebuffer for the display's current
00189      * resolution.
00190      *
00191      *  @param num the number of framebuffers, should be >= 1
00192      *  @param res the resolution (default is the one that the display is using)
00193      *  @returns new framebuffers or NULL if out of memory 
00194      */
00195     virtual void* allocateFramebuffers(uint32_t num=1, Resolution res=Resolution_16bit_rgb565) = 0;
00196 };
00197 
00198 #endif