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 */ 37typedef struct QFrameBuffer QFrameBuffer; 38 39 40typedef 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 47struct 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 */ 75extern int 76qframebuffer_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 */ 84extern void 85qframebuffer_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 */ 91extern void 92qframebuffer_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 */ 100typedef 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 */ 110typedef 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 */ 117typedef 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 */ 122typedef 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 */ 129extern void 130qframebuffer_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 */ 142typedef 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 */ 148typedef 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 */ 153typedef void (*QFrameBufferDetachFunc) ( void* opaque ); 154 155/* set the producer of a given framebuffer */ 156extern void 157qframebuffer_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 */ 166extern void 167qframebuffer_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 */ 172extern void 173qframebuffer_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 */ 179extern void 180qframebuffer_poll( QFrameBuffer* qfbuff ); 181 182/* finalize a framebuffer, release its pixel buffer. Should be called 183 * from the framebuffer object's owner 184 */ 185extern void 186qframebuffer_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 */ 192extern void 193qframebuffer_check_updates( void ); 194 195/* call this function periodically to force a poll on all franebuffers 196 */ 197extern void 198qframebuffer_pulse( void ); 199 200/* this is called by the emulator. for each registered framebuffer, call 201 * its producer's Invalidate method, if any 202 */ 203extern void 204qframebuffer_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 */ 218extern void 219qframebuffer_fifo_add( QFrameBuffer* qfbuff ); 220 221/* retrieve a frame buffer object from the global FIFO list */ 222extern QFrameBuffer* 223qframebuffer_fifo_get( void ); 224 225/* */ 226 227#endif /* _ANDROID_FRAMEBUFFER_H_ */ 228