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