1 /* Copyright (C) 2007-2008 The Android Open Source Project 2 ** 3 ** This software is licensed under the terms of the GNU General Public 4 ** License version 2, as published by the Free Software Foundation, and 5 ** may be copied, distributed, and modified under those terms. 6 ** 7 ** This program is distributed in the hope that it will be useful, 8 ** but WITHOUT ANY WARRANTY; without even the implied warranty of 9 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 10 ** GNU General Public License for more details. 11 */ 12 #ifndef _ANDROID_FRAMEBUFFER_H_ 13 #define _ANDROID_FRAMEBUFFER_H_ 14 15 /* A simple abstract interface to framebuffer displays. this is used to 16 * de-couple hardware emulation from final display. 17 * 18 * Each QFrameBuffer object holds a pixel buffer that is shared between 19 * one 'Producer' and one or more 'Clients' 20 * 21 * The Producer is in charge of updating the pixel buffer from the state 22 * of the emulated VRAM. A Client listens to updates to the pixel buffer, 23 * sent from the producer through qframebuffer_update()/_rotate() and 24 * displays them. 25 * 26 * note the 'rotation' field: it can take values 0, 1, 2 or 3 and corresponds 27 * to a rotation that must be performed to the pixels stored in the framebuffer 28 * *before* displaying them a value of 1 corresponds to a rotation of 29 * 90 clockwise-degrees, when the framebuffer is rotated 90 or 270 degrees, 30 * its width/height are swapped automatically 31 * 32 * phys_width_mm and phys_height_mm are physical dimensions expressed 33 * in millimeters 34 * 35 * More about the client/producer relationships below. 36 */ 37 typedef struct QFrameBuffer QFrameBuffer; 38 39 40 typedef enum { 41 QFRAME_BUFFER_NONE = 0, 42 QFRAME_BUFFER_RGB565 = 1, 43 QFRAME_BUFFER_RGBX_8888 = 2, 44 QFRAME_BUFFER_MAX /* do not remove */ 45 } QFrameBufferFormat; 46 47 struct QFrameBuffer { 48 int width; /* width in pixels */ 49 int height; /* height in pixels */ 50 int pitch; /* bytes per line */ 51 int bits_per_pixel; /* bits per pixel */ 52 int bytes_per_pixel; /* bytes per pixel */ 53 int rotation; /* rotation to be applied when displaying */ 54 QFrameBufferFormat format; 55 void* pixels; /* pixel buffer */ 56 57 int phys_width_mm; 58 int phys_height_mm; 59 60 /* extra data that is handled by the framebuffer implementation */ 61 void* extra; 62 63 }; 64 65 /* the default dpi resolution of a typical framebuffer. this is an average 66 * between various prototypes being used during the development of the 67 * Android system... 68 */ 69 #define DEFAULT_FRAMEBUFFER_DPI 165 70 71 72 /* initialize a framebuffer object and allocate its pixel buffer */ 73 /* this computes phys_width_mm and phys_height_mm assuming a 165 dpi screen */ 74 /* returns -1 in case of error, 0 otherwise */ 75 extern int 76 qframebuffer_init( QFrameBuffer* qfbuff, 77 int width, 78 int height, 79 int rotation, 80 QFrameBufferFormat format ); 81 82 /* recompute phys_width_mm and phys_height_mm according to the emulated 83 * screen DPI settings */ 84 extern void 85 qframebuffer_set_dpi( QFrameBuffer* qfbuff, 86 int x_dpi, 87 int y_dpi ); 88 89 /* alternative to qframebuffer_set_dpi where one can set the physical 90 * dimensions directly in millimeters. for the record 1 inch = 25.4 mm */ 91 extern void 92 qframebuffer_set_mm( QFrameBuffer* qfbuff, 93 int width_mm, 94 int height_mm ); 95 96 /* the Client::Update method is called to instruct a client that a given 97 * rectangle of the framebuffer pixels was updated and needs to be 98 * redrawn. 99 */ 100 typedef void (*QFrameBufferUpdateFunc)( void* opaque, int x, int y, 101 int w, int h ); 102 103 /* the Client::Rotate method is called to instruct the client that a 104 * framebuffer's internal rotation has changed. This is the rotation 105 * that must be applied before displaying the pixels. 106 * 107 * Note that it is assumed that all framebuffer pixels have changed too 108 * so the client should call its Update method as well. 109 */ 110 typedef void (*QFrameBufferRotateFunc)( void* opaque, int rotation ); 111 112 /* the Client::Poll method is called periodically to poll for input 113 * events and act on them. Putting this here is not 100% pure but 114 * make things simpler due to QEMU's weird architecture where the 115 * GUI timer drivers event polling. 116 */ 117 typedef void (*QFrameBufferPollFunc)( void* opaque ); 118 119 /* the Client::Done func tells a client that a framebuffer object was freed. 120 * no more reference to its pixels should be done. 121 */ 122 typedef void (*QFrameBufferDoneFunc) ( void* opaque ); 123 124 /* add one client to a given framebuffer. 125 * the current implementation only allows one client per frame-buffer, 126 * but we could allow more for various reasons (e.g. displaying the 127 * framebuffer + dispatching it through VNC at the same time) 128 */ 129 extern void 130 qframebuffer_add_client( QFrameBuffer* qfbuff, 131 void* fb_opaque, 132 QFrameBufferUpdateFunc fb_update, 133 QFrameBufferRotateFunc fb_rotate, 134 QFrameBufferPollFunc fb_poll, 135 QFrameBufferDoneFunc fb_done ); 136 137 /* Producer::CheckUpdate is called to let the producer check the 138 * VRAM state (e.g. VRAM dirty pages) to see if anything changed since the 139 * last call to the method. When true, the method should call either 140 * qframebuffer_update() or qframebuffer_rotate() with the appropriate values. 141 */ 142 typedef void (*QFrameBufferCheckUpdateFunc)( void* opaque ); 143 144 /* Producer::Invalidate tells the producer that the next call to 145 * CheckUpdate should act as if the whole content of VRAM had changed. 146 * this is normally done to force client initialization/refreshes. 147 */ 148 typedef void (*QFrameBufferInvalidateFunc) ( void* opaque ); 149 150 /* the Producer::Detach method is used to tell the producer that the 151 * underlying QFrameBuffer object is about to be de-allocated. 152 */ 153 typedef void (*QFrameBufferDetachFunc) ( void* opaque ); 154 155 /* set the producer of a given framebuffer */ 156 extern void 157 qframebuffer_set_producer( QFrameBuffer* qfbuff, 158 void* opaque, 159 QFrameBufferCheckUpdateFunc fb_check, 160 QFrameBufferInvalidateFunc fb_invalidate, 161 QFrameBufferDetachFunc fb_detach ); 162 163 /* tell a client that a rectangle region has been updated in the framebuffer 164 * pixel buffer this is typically called from a Producer::CheckUpdate method 165 */ 166 extern void 167 qframebuffer_update( QFrameBuffer* qfbuff, int x, int y, int w, int h ); 168 169 /* rotate the framebuffer (may swap width/height), and tell all clients. 170 * Should be called from a Producer::CheckUpdate method 171 */ 172 extern void 173 qframebuffer_rotate( QFrameBuffer* qfbuff, int rotation ); 174 175 /* this function is used to poll a framebuffer's client for input 176 * events. Should be called either explicitely, or through qframebuffer_pulse() 177 * periodically. 178 */ 179 extern void 180 qframebuffer_poll( QFrameBuffer* qfbuff ); 181 182 /* finalize a framebuffer, release its pixel buffer. Should be called 183 * from the framebuffer object's owner 184 */ 185 extern void 186 qframebuffer_done( QFrameBuffer* qfbuff ); 187 188 189 /* this is called repeatedly by the emulator. for each registered framebuffer, 190 * call its producer's CheckUpdate method, if any. 191 */ 192 extern void 193 qframebuffer_check_updates( void ); 194 195 /* call this function periodically to force a poll on all franebuffers 196 */ 197 extern void 198 qframebuffer_pulse( void ); 199 200 /* this is called by the emulator. for each registered framebuffer, call 201 * its producer's Invalidate method, if any 202 */ 203 extern void 204 qframebuffer_invalidate_all( void ); 205 206 /* 207 * to completely separate the implementation of clients, producers, and skins, 208 * we use a simple global FIFO list of QFrameBuffer objects. 209 * 210 * qframebuffer_fifo_add() is typically called by the emulator initialization 211 * depending on the emulated device's configuration 212 * 213 * qframebuffer_fifo_get() is typically called by a hardware framebuffer 214 * emulation. 215 */ 216 217 /* add a new constructed frame buffer object to our global list */ 218 extern void 219 qframebuffer_fifo_add( QFrameBuffer* qfbuff ); 220 221 /* retrieve a frame buffer object from the global FIFO list */ 222 extern QFrameBuffer* 223 qframebuffer_fifo_get( void ); 224 225 /* */ 226 227 #endif /* _ANDROID_FRAMEBUFFER_H_ */ 228