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