1 // Copyright 2015 The Android Open Source Project 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 #pragma once 15 16 #include <stdint.h> 17 18 /* A simple abstract interface to framebuffer displays. this is used to 19 * de-couple hardware emulation from final display. 20 * 21 * Each QFrameBuffer object holds a pixel buffer that is shared between 22 * one 'Producer' and one or more 'Clients' 23 * 24 * The Producer is in charge of updating the pixel buffer from the state 25 * of the emulated VRAM. A Client listens to updates to the pixel buffer, 26 * sent from the producer through qframebuffer_update()/_rotate() and 27 * displays them. 28 * 29 * note the 'rotation' field: it can take values 0, 1, 2 or 3 and corresponds 30 * to a rotation that must be performed to the pixels stored in the framebuffer 31 * *before* displaying them a value of 1 corresponds to a rotation of 32 * 90 clockwise-degrees, when the framebuffer is rotated 90 or 270 degrees, 33 * its width/height are swapped automatically 34 * 35 * phys_width_mm and phys_height_mm are physical dimensions expressed 36 * in millimeters 37 * 38 * More about the client/producer relationships below. 39 */ 40 typedef struct QFrameBuffer QFrameBuffer; 41 42 43 typedef enum { 44 QFRAME_BUFFER_NONE = 0, 45 QFRAME_BUFFER_RGB565 = 1, 46 QFRAME_BUFFER_RGBX_8888 = 2, 47 QFRAME_BUFFER_MAX /* do not remove */ 48 } QFrameBufferFormat; 49 50 struct QFrameBuffer { 51 int width; /* width in pixels */ 52 int height; /* height in pixels */ 53 int pitch; /* bytes per line */ 54 int bits_per_pixel; /* bits per pixel */ 55 int bytes_per_pixel; /* bytes per pixel */ 56 int rotation; /* rotation to be applied when displaying */ 57 QFrameBufferFormat format; 58 void* pixels; /* pixel buffer */ 59 60 int phys_width_mm; 61 int phys_height_mm; 62 63 /* extra data that is handled by the framebuffer implementation */ 64 void* extra; 65 66 }; 67 68 /* the default dpi resolution of a typical framebuffer. this is an average 69 * between various prototypes being used during the development of the 70 * Android system... 71 */ 72 #define DEFAULT_FRAMEBUFFER_DPI 165 73 74 /* initialize a framebuffer object and allocate its pixel buffer */ 75 /* this computes phys_width_mm and phys_height_mm assuming a 165 dpi screen */ 76 /* returns -1 in case of error, 0 otherwise */ 77 extern int 78 qframebuffer_init( QFrameBuffer* qfbuff, 79 int width, 80 int height, 81 int rotation, 82 QFrameBufferFormat format ); 83 84 /* initializes a dummy framebuffer object with no pixel buffer. */ 85 /* This is simply to set up the callbacks to invalidate and fetch the */ 86 /* current frame in no-window mode for screen recording. */ 87 extern int qframebuffer_init_no_window(QFrameBuffer* qtbuff); 88 89 /* recompute phys_width_mm and phys_height_mm according to the emulated 90 * screen DPI settings */ 91 extern void 92 qframebuffer_set_dpi( QFrameBuffer* qfbuff, 93 int x_dpi, 94 int y_dpi ); 95 96 /* alternative to qframebuffer_set_dpi where one can set the physical 97 * dimensions directly in millimeters. for the record 1 inch = 25.4 mm */ 98 extern void 99 qframebuffer_set_mm( QFrameBuffer* qfbuff, 100 int width_mm, 101 int height_mm ); 102 103 /* the Client::Update method is called to instruct a client that a given 104 * rectangle of the framebuffer pixels was updated and needs to be 105 * redrawn. 106 */ 107 typedef void (*QFrameBufferUpdateFunc)( void* opaque, int x, int y, 108 int w, int h ); 109 110 /* the Client::Rotate method is called to instruct the client that a 111 * framebuffer's internal rotation has changed. This is the rotation 112 * that must be applied before displaying the pixels. 113 * 114 * Note that it is assumed that all framebuffer pixels have changed too 115 * so the client should call its Update method as well. 116 */ 117 typedef void (*QFrameBufferRotateFunc)( void* opaque, int rotation ); 118 119 /* the Client::Poll method is called periodically to poll for input 120 * events and act on them. Putting this here is not 100% pure but 121 * make things simpler due to QEMU's weird architecture where the 122 * GUI timer drivers event polling. 123 */ 124 typedef void (*QFrameBufferPollFunc)( void* opaque ); 125 126 /* the Client::Done func tells a client that a framebuffer object was freed. 127 * no more reference to its pixels should be done. 128 */ 129 typedef void (*QFrameBufferDoneFunc) ( void* opaque ); 130 131 /* add one client to a given framebuffer. 132 * the current implementation only allows one client per frame-buffer, 133 * but we could allow more for various reasons (e.g. displaying the 134 * framebuffer + dispatching it through VNC at the same time) 135 */ 136 extern void 137 qframebuffer_add_client( QFrameBuffer* qfbuff, 138 void* fb_opaque, 139 QFrameBufferUpdateFunc fb_update, 140 QFrameBufferRotateFunc fb_rotate, 141 QFrameBufferPollFunc fb_poll, 142 QFrameBufferDoneFunc fb_done ); 143 144 /* Producer::CheckUpdate is called to let the producer check the 145 * VRAM state (e.g. VRAM dirty pages) to see if anything changed since the 146 * last call to the method. When true, the method should call either 147 * qframebuffer_update() or qframebuffer_rotate() with the appropriate values. 148 */ 149 typedef void (*QFrameBufferCheckUpdateFunc)( void* opaque ); 150 151 /* Producer::Invalidate tells the producer that the next call to 152 * CheckUpdate should act as if the whole content of VRAM had changed. 153 * this is normally done to force client initialization/refreshes. 154 */ 155 typedef void (*QFrameBufferInvalidateFunc) ( void* opaque ); 156 157 /* the Producer::Detach method is used to tell the producer that the 158 * underlying QFrameBuffer object is about to be de-allocated. 159 */ 160 typedef void (*QFrameBufferDetachFunc) ( void* opaque ); 161 162 /* set the producer of a given framebuffer */ 163 extern void 164 qframebuffer_set_producer( QFrameBuffer* qfbuff, 165 void* opaque, 166 QFrameBufferCheckUpdateFunc fb_check, 167 QFrameBufferInvalidateFunc fb_invalidate, 168 QFrameBufferDetachFunc fb_detach ); 169 170 /* tell a client that a rectangle region has been updated in the framebuffer 171 * pixel buffer this is typically called from a Producer::CheckUpdate method 172 */ 173 extern void 174 qframebuffer_update( QFrameBuffer* qfbuff, int x, int y, int w, int h ); 175 176 /* rotate the framebuffer (may swap width/height), and tell all clients. 177 * Should be called from a Producer::CheckUpdate method 178 */ 179 extern void 180 qframebuffer_rotate( QFrameBuffer* qfbuff, int rotation ); 181 182 /* this function is used to poll a framebuffer's client for input 183 * events. Should be called either explicitely, or through qframebuffer_pulse() 184 * periodically. 185 */ 186 extern void 187 qframebuffer_poll( QFrameBuffer* qfbuff ); 188 189 /* finalize a framebuffer, release its pixel buffer. Should be called 190 * from the framebuffer object's owner 191 */ 192 extern void 193 qframebuffer_done( QFrameBuffer* qfbuff ); 194 195 196 /* this is called repeatedly by the emulator. for each registered framebuffer, 197 * call its producer's CheckUpdate method, if any. 198 */ 199 extern void 200 qframebuffer_check_updates( void ); 201 202 /* call this function periodically to force a poll on all franebuffers 203 */ 204 extern void 205 qframebuffer_pulse( void ); 206 207 /* this is called by the emulator. for each registered framebuffer, call 208 * its producer's Invalidate method, if any 209 */ 210 extern void 211 qframebuffer_invalidate_all( void ); 212 213 /* 214 * to completely separate the implementation of clients, producers, and skins, 215 * we use a simple global FIFO list of QFrameBuffer objects. 216 * 217 * qframebuffer_fifo_add() is typically called by the emulator initialization 218 * depending on the emulated device's configuration 219 * 220 * qframebuffer_fifo_get() is typically called by a hardware framebuffer 221 * emulation. 222 */ 223 224 /* add a new constructed frame buffer object to our global list */ 225 extern void 226 qframebuffer_fifo_add( QFrameBuffer* qfbuff ); 227 228 /* retrieve a frame buffer object from the global FIFO list */ 229 extern QFrameBuffer* 230 qframebuffer_fifo_get( void ); 231 232 /* */ 233 // This is an interface for Qemu display interaction 234 235 // Called when display is updated 236 // |opaque| - a user-supplied value to pass back 237 // |x|, |y|, |w|, |h| - boundaries of the updated area 238 typedef void (*AndroidDisplayUpdateCallback)(void* opaque, int x, int y, 239 int w, int h); 240 241 typedef struct QAndroidDisplayAgent { 242 // Fills in frame buffer parameters into the passed variables 243 // |w|, |h| - width and height 244 // |lineSize| - bytes per line 245 // |bytesPerPixel| - bytes per pixel 246 // |frameBufferData| - pointer to the raw frame buffer data 247 void (*getFrameBuffer)(int* w, int* h, int* lineSize, int* bytesPerPixel, 248 uint8_t** frameBufferData); 249 250 // Registers a callback which is called every time frame buffer content 251 // is updated 252 // |callback| - a callback to call 253 // |opaque| - user data to pass to the callback 254 void (*registerUpdateListener)(AndroidDisplayUpdateCallback callback, 255 void* opaque); 256 257 // Unregisters a callback that was registered. 258 // |callback| - the callback to unregister 259 void (*unregisterUpdateListener)(AndroidDisplayUpdateCallback callback); 260 261 // Initializes the callback for invalidating and checking updates on a 262 // framebuffer in no-window mode (gpu guest). |qf| is simply a dummy 263 // framebuffer. It just needs to attach the necessary callbacks. 264 void (*initFrameBufferNoWindow)(QFrameBuffer* qf); 265 } QAndroidDisplayAgent; 266