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 _QEMU_FRAMEBUFFER_H_ 13 #define _QEMU_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_MAX /* do not remove */ 44 } QFrameBufferFormat; 45 46 struct QFrameBuffer { 47 int width; /* width in pixels */ 48 int height; /* height in pixels */ 49 int pitch; /* bytes per line */ 50 int rotation; /* rotation to be applied when displaying */ 51 QFrameBufferFormat format; 52 void* pixels; /* pixel buffer */ 53 54 int phys_width_mm; 55 int phys_height_mm; 56 57 /* extra data that is handled by the framebuffer implementation */ 58 void* extra; 59 60 }; 61 62 /* the default dpi resolution of a typical framebuffer. this is an average 63 * between various prototypes being used during the development of the 64 * Android system... 65 */ 66 #define DEFAULT_FRAMEBUFFER_DPI 165 67 68 69 /* initialize a framebuffer object and allocate its pixel buffer */ 70 /* this computes phys_width_mm and phys_height_mm assuming a 165 dpi screen */ 71 /* returns -1 in case of error, 0 otherwise */ 72 extern int 73 qframebuffer_init( QFrameBuffer* qfbuff, 74 int width, 75 int height, 76 int rotation, 77 QFrameBufferFormat format ); 78 79 /* recompute phys_width_mm and phys_height_mm according to the emulated 80 * screen DPI settings */ 81 extern void 82 qframebuffer_set_dpi( QFrameBuffer* qfbuff, 83 int x_dpi, 84 int y_dpi ); 85 86 /* alternative to qframebuffer_set_dpi where one can set the physical 87 * dimensions directly in millimeters. for the record 1 inch = 25.4 mm */ 88 extern void 89 qframebuffer_set_mm( QFrameBuffer* qfbuff, 90 int width_mm, 91 int height_mm ); 92 93 /* the Client::Update method is called to instruct a client that a given 94 * rectangle of the framebuffer pixels was updated and needs to be 95 * redrawn. 96 */ 97 typedef void (*QFrameBufferUpdateFunc)( void* opaque, int x, int y, 98 int w, int h ); 99 100 /* the Client::Rotate method is called to instruct the client that a 101 * framebuffer's internal rotation has changed. This is the rotation 102 * that must be applied before displaying the pixels. 103 * 104 * Note that it is assumed that all framebuffer pixels have changed too 105 * so the client should call its Update method as well. 106 */ 107 typedef void (*QFrameBufferRotateFunc)( void* opaque, int rotation ); 108 109 /* the Client::Done func tells a client that a framebuffer object was freed. 110 * no more reference to its pixels should be done. 111 */ 112 typedef void (*QFrameBufferDoneFunc) ( void* opaque ); 113 114 /* add one client to a given framebuffer. 115 * the current implementation only allows one client per frame-buffer, 116 * but we could allow more for various reasons (e.g. displaying the 117 * framebuffer + dispatching it through VNC at the same time) 118 */ 119 extern void 120 qframebuffer_add_client( QFrameBuffer* qfbuff, 121 void* fb_opaque, 122 QFrameBufferUpdateFunc fb_update, 123 QFrameBufferRotateFunc fb_rotate, 124 QFrameBufferDoneFunc fb_done ); 125 126 /* Producer::CheckUpdate is called to let the producer check the 127 * VRAM state (e.g. VRAM dirty pages) to see if anything changed since the 128 * last call to the method. When true, the method should call either 129 * qframebuffer_update() or qframebuffer_rotate() with the appropriate values. 130 */ 131 typedef void (*QFrameBufferCheckUpdateFunc)( void* opaque ); 132 133 /* Producer::Invalidate tells the producer that the next call to 134 * CheckUpdate should act as if the whole content of VRAM had changed. 135 * this is normally done to force client initialization/refreshes. 136 */ 137 typedef void (*QFrameBufferInvalidateFunc) ( void* opaque ); 138 139 /* the Producer::Detach method is used to tell the producer that the 140 * underlying QFrameBuffer object is about to be de-allocated. 141 */ 142 typedef void (*QFrameBufferDetachFunc) ( void* opaque ); 143 144 /* set the producer of a given framebuffer */ 145 extern void 146 qframebuffer_set_producer( QFrameBuffer* qfbuff, 147 void* opaque, 148 QFrameBufferCheckUpdateFunc fb_check, 149 QFrameBufferInvalidateFunc fb_invalidate, 150 QFrameBufferDetachFunc fb_detach ); 151 152 /* tell a client that a rectangle region has been updated in the framebuffer 153 * pixel buffer this is typically called from a Producer::CheckUpdate method 154 */ 155 extern void 156 qframebuffer_update( QFrameBuffer* qfbuff, int x, int y, int w, int h ); 157 158 /* rotate the framebuffer (may swap width/height), and tell all clients. 159 * Should be called from a Producer::CheckUpdate method 160 */ 161 extern void 162 qframebuffer_rotate( QFrameBuffer* qfbuff, int rotation ); 163 164 /* finalize a framebuffer, release its pixel buffer. Should be called 165 * from the framebuffer object's owner 166 */ 167 extern void 168 qframebuffer_done( QFrameBuffer* qfbuff ); 169 170 171 /* this is called repeatedly by the emulator. for each registered framebuffer, 172 * call its producer's CheckUpdate method, if any. 173 */ 174 extern void 175 qframebuffer_check_updates( void ); 176 177 /* this is called by the emulator. for each registered framebuffer, call 178 * its producer's Invalidate method, if any 179 */ 180 extern void 181 qframebuffer_invalidate_all( void ); 182 183 /* 184 * to completely separate the implementation of clients, producers, and skins, 185 * we use a simple global FIFO list of QFrameBuffer objects. 186 * 187 * qframebuffer_fifo_add() is typically called by the emulator initialization 188 * depending on the emulated device's configuration 189 * 190 * qframebuffer_fifo_get() is typically called by a hardware framebuffer 191 * emulation. 192 */ 193 194 /* add a new constructed frame buffer object to our global list */ 195 extern void 196 qframebuffer_fifo_add( QFrameBuffer* qfbuff ); 197 198 /* retrieve a frame buffer object from the global FIFO list */ 199 extern QFrameBuffer* 200 qframebuffer_fifo_get( void ); 201 202 /* */ 203 204 #endif /* _QEMU_FRAMEBUFFER_H_ */ 205 206