Diff: Display/Display.h

Revision:

9:a33326afd686

Parent:

0:6b68dac0d986

Child:

10:1ac4b213f0f7

--- a/Display/Display.h	Thu Dec 11 11:50:29 2014 +0000
+++ b/Display/Display.h	Thu Dec 11 18:23:07 2014 +0000
@@ -19,6 +19,39 @@
 
 #include "mbed.h"
 
+/**
+ * Display example
+ *
+ * @code
+ * #include "mbed.h"
+ * #include "DMBoard.h"
+ *
+ * int main(void) {
+ *    // initialize the display
+ *    DMBoard::instance().init();
+ *
+ *    // allocate one framebuffer
+ *    Display* disp = DMBoard::instance().display();
+ *    uint16_t* fb = (uint16_t*)disp->allocateFramebuffer();
+ *    if (fb == NULL) {
+ *      DMBoard::instance().logger()->printf("Failed to allocate memory for framebuffer\r\n");
+ *      mbed_die();
+ *    }
+ *
+ *    // draw something on the framebuffer
+ *    ...
+ *
+ *    // turn on the display
+ *    disperr = disp->powerUp(fb);
+ *    if (disperr != Display::Ok) {
+ *      DMBoard::instance().logger()->printf("Failed to initialize the display, got error %d\r\n", disperr);
+ *      mbed_die();
+ *    }
+ *
+ *    ...
+ * }
+ * @endcode
+ */
 class Display {
 public:
     enum Constants {
@@ -39,6 +72,10 @@
         Resolution_24bit_rgb888 = 24,
     };
     
+    /** Get the only instance of the Display
+     *
+     *  @returns The display
+     */
     static Display& instance()
     {
         static Display singleton;
@@ -46,7 +83,7 @@
     }
   
 
-    /** Initializes the wanted features
+    /** Initializes the display but does not turn it on
      *
      *  @returns
      *       Ok on success
@@ -54,7 +91,7 @@
      */
     DisplayError init();
   
-    /** Initializes the wanted features
+    /** Turns the display on with the specified framebuffer showing
      *
      *  @returns
      *       Ok on success
@@ -62,7 +99,7 @@
      */
     DisplayError powerUp(void* framebuffer, Resolution wanted = Resolution_16bit_rgb565);
   
-    /** Initializes the wanted features
+    /** Turns the display off
      *
      *  @returns
      *       Ok on success
@@ -84,8 +121,37 @@
     uint32_t fbSize() { return _fbSize; }
     bool landscape() { return _landscape; }
     bool isSupported(Resolution res);
+    
+    /** Replaces the current framebuffer.
+     *
+     * Note that this requires the caller or someone else to have a
+     * reference to the existing framebuffer, otherwise that memory
+     * is lost.
+     *
+     *  @param buff the new framebuffer
+     */
     void setFramebuffer(void* buff);
+    
+    /** Replaces the current framebuffer with the specified one.
+     *
+     * This function as opposed to the setFramebuffer() one does return
+     * the old framebuffer. This way the caller can save the old one and
+     * then swap it back when done.
+     *
+     *  @param buff the new framebuffer
+     *  @returns the old framebuffer
+     */
     void* swapFramebuffer(void* buff);
+    
+    /** Allocate enough memory for one framebuffer
+     *
+     * This function is a to make it easier to allocate memory for framebuffers
+     * as the number of bytes needed depends on width, height and bytes per pixel.
+     *
+     * Free the allocated memory when done using the free() function.
+     *
+     *  @returns a new framebuffer or NULL if out of memory 
+     */
     void* allocateFramebuffer(Resolution res=Resolution_16bit_rgb565);
 
 private:
@@ -121,4 +187,3 @@
 };
 
 #endif
-