1 |
786 |
skrzyp |
|
2 |
|
|
|
3 |
|
|
|
4 |
|
|
|
5 |
|
|
|
6 |
|
|
|
7 |
|
|
|
8 |
|
|
|
9 |
|
|
|
10 |
|
|
|
11 |
|
|
|
12 |
|
|
|
13 |
|
|
|
14 |
|
|
|
15 |
|
|
|
16 |
|
|
|
17 |
|
|
|
18 |
|
|
|
19 |
|
|
|
20 |
|
|
|
21 |
|
|
|
22 |
|
|
|
23 |
|
|
|
24 |
|
|
|
25 |
|
|
|
26 |
|
|
|
27 |
|
|
|
28 |
|
|
|
29 |
|
|
|
30 |
|
|
|
31 |
|
|
|
32 |
|
|
|
33 |
|
|
|
34 |
|
|
|
35 |
|
|
Framebuffer Support
|
36 |
|
|
|
37 |
|
|
|
38 |
|
|
|
39 |
|
|
|
40 |
|
|
|
41 |
|
|
Overview
|
42 |
|
|
|
43 |
|
|
|
44 |
|
|
Overview
|
45 |
|
|
eCos Support for Framebuffer Devices
|
46 |
|
|
|
47 |
|
|
|
48 |
|
|
|
49 |
|
|
Description
|
50 |
|
|
|
51 |
|
|
Framebuffer devices are the most common way for a computer system to
|
52 |
|
|
display graphical output to users. There are immense variations in the
|
53 |
|
|
implementations of such devices. CYGPKG_IO_FRAMEBUF
|
54 |
|
|
provides an abstraction layer for use by application code and other
|
55 |
|
|
packages. It defines an API for manipulating framebuffers, mapping
|
56 |
|
|
this API on to functionality provided by the appropriate device
|
57 |
|
|
driver. It also defines the interface which such device drivers should
|
58 |
|
|
implement. For simple hardware it provides default implementations of
|
59 |
|
|
much of this interface, greatly reducing the effort needed to write a
|
60 |
|
|
device driver.
|
61 |
|
|
|
62 |
|
|
|
63 |
|
|
This package does not constitute a graphics library. It does not
|
64 |
|
|
implement functionality like drawing text or arbitrary lines, let
|
65 |
|
|
alone any kind of windowing system. Instead it operates at the lower
|
66 |
|
|
level of individual pixels and blocks of pixels, in addition to
|
67 |
|
|
control operations such as hardware initialization. Some applications
|
68 |
|
|
may use the framebuffer API directly. Others will instead use a
|
69 |
|
|
higher-level graphics library, and it is that library which uses the
|
70 |
|
|
framebuffer API.
|
71 |
|
|
|
72 |
|
|
|
73 |
|
|
It is assumed that users are already familiar with the fundamentals of
|
74 |
|
|
computer graphics, and no attempt is made here to explain terms like
|
75 |
|
|
display depth, palette or pixel.
|
76 |
|
|
|
77 |
|
|
|
78 |
|
|
|
79 |
|
|
This package is work-in-progress. The support for 1bpp, 2bpp and 4bpp
|
80 |
|
|
display depths is incomplete. For double-buffered displays the code
|
81 |
|
|
does not yet maintain a bounding box of the updated parts of the
|
82 |
|
|
display. The package has also been designed to allow for
|
83 |
|
|
expansion with new
|
84 |
|
|
functionality.
|
85 |
|
|
|
86 |
|
|
|
87 |
|
|
|
88 |
|
|
|
89 |
|
|
|
90 |
|
|
Configuration
|
91 |
|
|
|
92 |
|
|
CYGPKG_IO_FRAMEBUF only contains
|
93 |
|
|
hardware-independent code. It should be complemented by one or more
|
94 |
|
|
framebuffer device drivers appropriate for the target platform. These
|
95 |
|
|
drivers may be specific to the platform, or they may be more generic
|
96 |
|
|
with platform-specific details such as the framebuffer memory base
|
97 |
|
|
address provided by the platform HAL. When creating a configuration
|
98 |
|
|
for a given target the device driver(s) will always be included
|
99 |
|
|
automatically (assuming one has been written or ported). However by
|
100 |
|
|
default this driver will be inactive and will not get built, so does
|
101 |
|
|
not add any unnecessary size overhead for applications which do not
|
102 |
|
|
require graphics. To activate the device driver
|
103 |
|
|
CYGPKG_IO_FRAMEBUF must be added explicitly to the
|
104 |
|
|
configuration, for example using
|
105 |
|
|
ecosconfig add framebuf. After this the
|
106 |
|
|
full framebuffer API will be available to other packages and to
|
107 |
|
|
application code.
|
108 |
|
|
|
109 |
|
|
|
110 |
|
|
This package contains very few configuration options. Instead it is
|
111 |
|
|
left to device drivers or higher-level code to provide appropriate
|
112 |
|
|
configurability. One option,
|
113 |
|
|
CYGFUN_IO_FRAMEBUF_INSTALL_DEFAULT_PALETTE, relates
|
114 |
|
|
to the initialization of
|
115 |
|
|
linkend="framebuf-colour-palette">paletted displays.
|
116 |
|
|
|
117 |
|
|
|
118 |
|
|
There are a number of calculated and inferred configuration options
|
119 |
|
|
and a number of interfaces. These provide information such as whether
|
120 |
|
|
or not there is a backlight. The most important one is
|
121 |
|
|
CYGDAT_IO_FRAMEBUF_DEVICES, which holds a list of
|
122 |
|
|
framebuffer identifiers for use with the
|
123 |
|
|
linkend="framebuf-api">macro-based API. If there is a single
|
124 |
|
|
framebuffer device driver which supports one display in either
|
125 |
|
|
landscape or portrait mode, the configuration option may hold a value
|
126 |
|
|
like 240x320x8 320x240x8r90.
|
127 |
|
|
|
128 |
|
|
|
129 |
|
|
|
130 |
|
|
|
131 |
|
|
Application Programmer Interfaces
|
132 |
|
|
|
133 |
|
|
Framebuffer devices require a difficult choice between flexibility and
|
134 |
|
|
performance. On the one hand the API should be able to support
|
135 |
|
|
multiple devices driving separate displays, or a single device
|
136 |
|
|
operating in different modes at different times. On the other hand
|
137 |
|
|
graphics tends to involve very large amounts of I/O: even something as
|
138 |
|
|
simple as drawing a background image can involve setting many
|
139 |
|
|
thousands of pixels. Efficiency requires avoiding all possible
|
140 |
|
|
overheads including function calls. Instead the API should make
|
141 |
|
|
extensive use of macros or inline functions. Ideally details of the
|
142 |
|
|
framebuffer device such as the stride would be known constants at
|
143 |
|
|
compile-time, giving the compiler as much opportunity as possible to
|
144 |
|
|
optimize the code. Clearly this is difficult if multiple framebuffer
|
145 |
|
|
devices are in use or if the device mode may get changed at run-time.
|
146 |
|
|
|
147 |
|
|
|
148 |
|
|
To meet the conflicting requirements the generic framebuffer package
|
149 |
|
|
provides two APIs: a fast macro API which requires selecting a single
|
150 |
|
|
framebuffer device at compile or configure time; and a slower function
|
151 |
|
|
API without this limitation. The two are very similar, for example:
|
152 |
|
|
|
153 |
|
|
|
154 |
|
|
#include <cyg/io/framebuf.h>
|
155 |
|
|
|
156 |
|
|
void
|
157 |
|
|
clear_screen(cyg_fb* fb, cyg_fb_colour colour)
|
158 |
|
|
{
|
159 |
|
|
cyg_fb_fill_block(fb, 0, 0,
|
160 |
|
|
fb->fb_width, fb->fb_height,
|
161 |
|
|
colour);
|
162 |
|
|
}
|
163 |
|
|
|
164 |
|
|
|
165 |
|
|
or the equivalent macro version:
|
166 |
|
|
|
167 |
|
|
|
168 |
|
|
#include <cyg/io/framebuf.h>
|
169 |
|
|
|
170 |
|
|
#define FRAMEBUF 240x320x8
|
171 |
|
|
|
172 |
|
|
void
|
173 |
|
|
clear_screen(cyg_fb_colour colour)
|
174 |
|
|
{
|
175 |
|
|
CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,
|
176 |
|
|
CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),
|
177 |
|
|
colour);
|
178 |
|
|
}
|
179 |
|
|
|
180 |
|
|
|
181 |
|
|
The function-based API works in terms of
|
182 |
|
|
cyg_fb structures, containing all the
|
183 |
|
|
information needed to manipulate the device. Each framebuffer device
|
184 |
|
|
driver will export one or more of these structures, for example
|
185 |
|
|
cyg_alaia_fb_240x320x8, and the driver
|
186 |
|
|
documentation should list the variable names. The macro API works in
|
187 |
|
|
terms of identifiers such as 240x320x8, and by a
|
188 |
|
|
series of substitutions the main macro gets expanded to the
|
189 |
|
|
appropriate device-specific code, usually inline. Again the device
|
190 |
|
|
driver documentation should list the supported identifiers. In
|
191 |
|
|
addition the configuration option
|
192 |
|
|
CYGDAT_IO_FRAMEBUF_DEVICES will contain the full
|
193 |
|
|
list. By convention the identifier will be specified by a
|
194 |
|
|
#define'd symbol such as
|
195 |
|
|
FRAMEBUF, or in the case of graphics libraries by a
|
196 |
|
|
configuration option.
|
197 |
|
|
|
198 |
|
|
|
199 |
|
|
If a platform has multiple framebuffer devices connected to different
|
200 |
|
|
displays then there will be separate cyg_fb
|
201 |
|
|
structures and macro identifiers for each one. In addition some
|
202 |
|
|
devices can operate in multiple modes. For example a PC VGA card can
|
203 |
|
|
operate in a monochome 640x480 mode, an 8bpp 320x200 mode, and many
|
204 |
|
|
other modes, but only one of these can be active at a time. The
|
205 |
|
|
different modes are also represented by different
|
206 |
|
|
cyg_fb structures and identifiers,
|
207 |
|
|
effectively treating the modes as separate devices. It is the
|
208 |
|
|
responsibility of higher-level code to ensure that only one mode is in
|
209 |
|
|
use at a time.
|
210 |
|
|
|
211 |
|
|
|
212 |
|
|
It is possible to use the macro API with more than one device,
|
213 |
|
|
basically by compiling the code twice with different values of
|
214 |
|
|
FRAMEBUF, taking appropriate care to avoid
|
215 |
|
|
identifier name clashes. This gives the higher performance of the
|
216 |
|
|
macros at the cost of increased code size.
|
217 |
|
|
|
218 |
|
|
|
219 |
|
|
All of the framebuffer API, including exports of the device-specific
|
220 |
|
|
cyg_fb structures, is available through a
|
221 |
|
|
single header file <cyg/io/framebuf.h>. The
|
222 |
|
|
API follows a number of conventions. Coordinates (0,0) correspond to
|
223 |
|
|
the top-left corner of the display. All functions and macros which
|
224 |
|
|
take a pair of coordinates have x first, y second. For block
|
225 |
|
|
operations these coordinates are followed by width, then height.
|
226 |
|
|
Coordinates and dimensions use cyg_ucount16 variables,
|
227 |
|
|
which for any processor should be the most efficient unsigned data
|
228 |
|
|
type with at least 16 bits - usually plain unsigned integers. Colours
|
229 |
|
|
are identified by cyg_fb_colour variables, again usually
|
230 |
|
|
unsigned integers.
|
231 |
|
|
|
232 |
|
|
|
233 |
|
|
To allow for the different variants of the English language, the API
|
234 |
|
|
allows for a number of alternate spellings. Colour and color can be
|
235 |
|
|
used interchangeably, so there are data types
|
236 |
|
|
cyg_fb_colour and cyg_fb_color, and
|
237 |
|
|
functions cyg_fb_make_colour and
|
238 |
|
|
cyg_fb_make_color. Similarly gray is accepted as
|
239 |
|
|
a variant of grey so the predefined colours
|
240 |
|
|
CYG_FB_DEFAULT_PALETTE_LIGHTGREY and
|
241 |
|
|
CYG_FB_DEFAULT_PALETTE_LIGHTGRAY are equivalent.
|
242 |
|
|
|
243 |
|
|
|
244 |
|
|
The API is split into the following categories:
|
245 |
|
|
|
246 |
|
|
|
247 |
|
|
|
248 |
|
|
parameters
|
249 |
|
|
|
250 |
|
|
getting information about a given framebuffer device such as width,
|
251 |
|
|
height and depth. Colours management is complicated so has its own
|
252 |
|
|
category.
|
253 |
|
|
|
254 |
|
|
|
255 |
|
|
|
256 |
|
|
control
|
257 |
|
|
|
258 |
|
|
operations such as switching the display on and off, and more
|
259 |
|
|
device-specific ones such as manipulating the backlight.
|
260 |
|
|
|
261 |
|
|
|
262 |
|
|
|
263 |
|
|
colours
|
264 |
|
|
|
265 |
|
|
determining the colour format (monochrome, paletted, &hellip),
|
266 |
|
|
manipulating the palette, or constructing true colours.
|
267 |
|
|
|
268 |
|
|
|
269 |
|
|
|
270 |
|
|
drawing
|
271 |
|
|
|
272 |
|
|
primitives for manipulating pixels and blocks of pixels.
|
273 |
|
|
|
274 |
|
|
|
275 |
|
|
|
276 |
|
|
iteration
|
277 |
|
|
|
278 |
|
|
efficiently iterating over blocks of pixels.
|
279 |
|
|
|
280 |
|
|
|
281 |
|
|
|
282 |
|
|
|
283 |
|
|
|
284 |
|
|
|
285 |
|
|
Thread Safety
|
286 |
|
|
|
287 |
|
|
The framebuffer API never performs any locking so is not thread-safe.
|
288 |
|
|
Instead it assumes that higher-level code such as a graphics library
|
289 |
|
|
performs any locking that may be needed. Adding a mutex lock and
|
290 |
|
|
unlock around every drawing primitive, including pixel writes, would
|
291 |
|
|
be prohibitively expensive.
|
292 |
|
|
|
293 |
|
|
|
294 |
|
|
It is also assumed that the framebuffer will only be updated from
|
295 |
|
|
thread context. With most hardware it will also be possible to access
|
296 |
|
|
a framebuffer from DSR or ISR context, but this should be avoided in
|
297 |
|
|
portable code.
|
298 |
|
|
|
299 |
|
|
|
300 |
|
|
|
301 |
|
|
|
302 |
|
|
|
303 |
|
|
|
304 |
|
|
|
305 |
|
|
|
306 |
|
|
|
307 |
|
|
|
308 |
|
|
Framebuffer Parameters
|
309 |
|
|
|
310 |
|
|
|
311 |
|
|
Parameters
|
312 |
|
|
determining framebuffer capabilities
|
313 |
|
|
|
314 |
|
|
|
315 |
|
|
|
316 |
|
|
|
317 |
|
|
#include <cyg/io/framebuf.h>
|
318 |
|
|
|
319 |
|
|
typedef struct cyg_fb {
|
320 |
|
|
cyg_ucount16 fb_depth;
|
321 |
|
|
cyg_ucount16 fb_format;
|
322 |
|
|
cyg_ucount16 fb_width;
|
323 |
|
|
cyg_ucount16 fb_height;
|
324 |
|
|
#ifdef CYGHWR_IO_FRAMEBUF_FUNCTIONALITY_VIEWPORT
|
325 |
|
|
cyg_ucount16 fb_viewport_width;
|
326 |
|
|
cyg_ucount16 fb_viewport_height;
|
327 |
|
|
#endif
|
328 |
|
|
void* fb_base;
|
329 |
|
|
cyg_ucount16 fb_stride;
|
330 |
|
|
cyg_uint32 fb_flags0;
|
331 |
|
|
…
|
332 |
|
|
} cyg_fb;
|
333 |
|
|
|
334 |
|
|
|
335 |
|
|
cyg_fb* CYG_FB_STRUCT
|
336 |
|
|
FRAMEBUF
|
337 |
|
|
|
338 |
|
|
|
339 |
|
|
cyg_ucount16 CYG_FB_DEPTH
|
340 |
|
|
FRAMEBUF
|
341 |
|
|
|
342 |
|
|
|
343 |
|
|
cyg_ucount16 CYG_FB_FORMAT
|
344 |
|
|
FRAMEBUF
|
345 |
|
|
|
346 |
|
|
|
347 |
|
|
cyg_ucount16 CYG_FB_WIDTH
|
348 |
|
|
FRAMEBUF
|
349 |
|
|
|
350 |
|
|
|
351 |
|
|
cyg_ucount16 CYG_FB_HEIGHT
|
352 |
|
|
FRAMEBUF
|
353 |
|
|
|
354 |
|
|
|
355 |
|
|
cyg_ucount16 CYG_FB_VIEWPORT_WIDTH
|
356 |
|
|
FRAMEBUF
|
357 |
|
|
|
358 |
|
|
|
359 |
|
|
cyg_ucount16 CYG_FB_VIEWPORT_HEIGHT
|
360 |
|
|
FRAMEBUF
|
361 |
|
|
|
362 |
|
|
|
363 |
|
|
void* CYG_FB_BASE
|
364 |
|
|
FRAMEBUF
|
365 |
|
|
|
366 |
|
|
|
367 |
|
|
cyg_ucount16 CYG_FB_STRIDE
|
368 |
|
|
FRAMEBUF
|
369 |
|
|
|
370 |
|
|
|
371 |
|
|
cyg_uint32 CYG_FB_FLAGS0
|
372 |
|
|
FRAMEBUF
|
373 |
|
|
|
374 |
|
|
|
375 |
|
|
|
376 |
|
|
|
377 |
|
|
|
378 |
|
|
Description
|
379 |
|
|
|
380 |
|
|
When developing an application for a specific platform the various
|
381 |
|
|
framebuffer parameters such as width and height are known, and the
|
382 |
|
|
code can be written accordingly. However when writing code that should
|
383 |
|
|
work on many platforms with different framebuffer devices, for example
|
384 |
|
|
a graphics library, the code must be able to get these parameters and
|
385 |
|
|
adapt.
|
386 |
|
|
|
387 |
|
|
|
388 |
|
|
Code using the function API can extract the parameters from the
|
389 |
|
|
cyg_fb structures at run-time. The macro API
|
390 |
|
|
provides dedicated macros for each parameter. These do not follow the
|
391 |
|
|
usual eCos convention where the result is provided via an extra
|
392 |
|
|
argument. Instead the result is returned as normal, and is guaranteed
|
393 |
|
|
to be a compile-time constant. This allows code like the following:
|
394 |
|
|
|
395 |
|
|
|
396 |
|
|
#if CYG_FB_DEPTH(FRAMEBUF) < 8
|
397 |
|
|
…
|
398 |
|
|
#else
|
399 |
|
|
…
|
400 |
|
|
#endif
|
401 |
|
|
|
402 |
|
|
|
403 |
|
|
or alternatively:
|
404 |
|
|
|
405 |
|
|
|
406 |
|
|
if (CYG_FB_DEPTH(FRAMEBUF) < 8) {
|
407 |
|
|
…
|
408 |
|
|
} else {
|
409 |
|
|
…
|
410 |
|
|
}
|
411 |
|
|
|
412 |
|
|
|
413 |
|
|
or:
|
414 |
|
|
|
415 |
|
|
|
416 |
|
|
switch (CYG_FB_DEPTH(FRAMEBUF)) {
|
417 |
|
|
case 1 : … break;
|
418 |
|
|
case 2 : … break;
|
419 |
|
|
case 4 : … break;
|
420 |
|
|
case 8 : … break;
|
421 |
|
|
case 16 : … break;
|
422 |
|
|
case 32 : … break;
|
423 |
|
|
}
|
424 |
|
|
|
425 |
|
|
|
426 |
|
|
In terms of the code actually generated by the compiler these
|
427 |
|
|
approaches have much the same effect. The macros expand to a
|
428 |
|
|
compile-time constant so unnecessary code can be easily eliminated.
|
429 |
|
|
|
430 |
|
|
|
431 |
|
|
The available parameters are as follows:
|
432 |
|
|
|
433 |
|
|
|
434 |
|
|
|
435 |
|
|
depth
|
436 |
|
|
|
437 |
|
|
The number of bits per pixel or bpp. The common depths are 1, 2, 4, 8,
|
438 |
|
|
16 and 32.
|
439 |
|
|
|
440 |
|
|
|
441 |
|
|
|
442 |
|
|
format
|
443 |
|
|
|
444 |
|
|
How the pixel values are mapped on to visible
|
445 |
|
|
linkend="framebuf-colour">colours, for example true colour
|
446 |
|
|
or paletted or greyscale.
|
447 |
|
|
|
448 |
|
|
|
449 |
|
|
|
450 |
|
|
width
|
451 |
|
|
height
|
452 |
|
|
|
453 |
|
|
The number of framebuffer pixels horizontally and vertically.
|
454 |
|
|
|
455 |
|
|
|
456 |
|
|
|
457 |
|
|
viewport width
|
458 |
|
|
viewport height
|
459 |
|
|
|
460 |
|
|
With some devices the framebuffer height and/or width are greater than
|
461 |
|
|
what the display can actually show. The display is said to offer a
|
462 |
|
|
viewport into the larger framebuffer. The number of visible pixels is
|
463 |
|
|
determined from the viewport width and height. The position of the
|
464 |
|
|
viewport is controlled via an
|
465 |
|
|
linkend="framebuf-control-ioctl-viewport">ioctl.
|
466 |
|
|
Within a cyg_fb structure these fields are
|
467 |
|
|
only present if
|
468 |
|
|
CYGHWR_IO_FRAMEBUF_FUNCTIONALITY_VIEWPORT
|
469 |
|
|
is defined, to avoid wasting data space on fields that are unnecessary
|
470 |
|
|
for the current platform. For the macro API the viewport macros should only be used
|
471 |
|
|
if CYG_FB_FLAGS0_VIEWPORT is set for the framebuffer:
|
472 |
|
|
|
473 |
|
|
|
474 |
|
|
#if (CYG_FB_FLAGS0(FRAMEBUF) & CYG_FB_FLAGS0_VIEWPORT)
|
475 |
|
|
…
|
476 |
|
|
#endif
|
477 |
|
|
|
478 |
|
|
|
479 |
|
|
|
480 |
|
|
base
|
481 |
|
|
stride
|
482 |
|
|
|
483 |
|
|
For linear
|
484 |
|
|
framebuffers these parameters provide the information needed to access
|
485 |
|
|
framebuffer memory. The stride is in bytes.
|
486 |
|
|
|
487 |
|
|
|
488 |
|
|
|
489 |
|
|
flags0
|
490 |
|
|
|
491 |
|
|
This gives further information about the hardware capabilities.
|
492 |
|
|
Some of this overlaps with other parameters, especially when it comes
|
493 |
|
|
to colour, because it is often easier to test for a single flag than
|
494 |
|
|
for a range of colour modes. The current flags are:
|
495 |
|
|
|
496 |
|
|
|
497 |
|
|
|
498 |
|
|
CYG_FB_FLAGS0_LINEAR_FRAMEBUFFER
|
499 |
|
|
|
500 |
|
|
Framebuffer memory is organized in a conventional fashion and can be
|
501 |
|
|
accessed directly by
|
502 |
|
|
higher-level code using the base and stride parameters.
|
503 |
|
|
|
504 |
|
|
|
505 |
|
|
|
506 |
|
|
CYG_FB_FLAGS0_LE
|
507 |
|
|
|
508 |
|
|
This flag is only relevant for 1bpp, 2bpp and 4bpp devices and
|
509 |
|
|
controls how the pixels are organized within each byte. If the flag is
|
510 |
|
|
set then the layout is little-endian: for a 1bpp device pixel (0,0)
|
511 |
|
|
occupies bit 0 of the first byte of framebuffer memory. The more
|
512 |
|
|
common layout is big-endian where pixel (0,0) occupies bit 7 of the
|
513 |
|
|
first byte.
|
514 |
|
|
|
515 |
|
|
|
516 |
|
|
|
517 |
|
|
CYG_FB_FLAGS0_TRUE_COLOUR
|
518 |
|
|
|
519 |
|
|
The framebuffer uses a true colour format where the value of each
|
520 |
|
|
pixel directly encodes the red, green and blue intensities. This is
|
521 |
|
|
common for 16bpp and 32bpp devices, and is occasionally used for 8bpp
|
522 |
|
|
devices.
|
523 |
|
|
|
524 |
|
|
|
525 |
|
|
|
526 |
|
|
CYG_FB_FLAGS0_PALETTE
|
527 |
|
|
|
528 |
|
|
The framebuffer uses a palette. A pixel value does not directly encode
|
529 |
|
|
the colours, but instead acts as an index into a separate table of
|
530 |
|
|
colour values. That table may be read-only or read-write. Paletted
|
531 |
|
|
displays are common for 8bpp and some 4bpp displays.
|
532 |
|
|
|
533 |
|
|
|
534 |
|
|
|
535 |
|
|
CYG_FB_FLAGS0_WRITEABLE_PALETTE
|
536 |
|
|
|
537 |
|
|
The palette is read-write.
|
538 |
|
|
|
539 |
|
|
|
540 |
|
|
|
541 |
|
|
CYG_FB_FLAGS0_DELAYED_PALETTE_UPDATE
|
542 |
|
|
|
543 |
|
|
Palette updates can be synchronized to a vertical blank, in other
|
544 |
|
|
words a brief time period when the display is not being updated,
|
545 |
|
|
by using CYG_FB_UPDATE_VERTICAL_RETRACE as the last
|
546 |
|
|
argument to cyg_fb_write_palette or
|
547 |
|
|
CYG_FB_WRITE_PALETTE. With some hardware updating
|
548 |
|
|
the palette in the middle of a screen update may result in visual noise.
|
549 |
|
|
|
550 |
|
|
|
551 |
|
|
|
552 |
|
|
CYG_FB_FLAGS0_VIEWPORT
|
553 |
|
|
|
554 |
|
|
The framebuffer contains more pixels than can be shown on the display.
|
555 |
|
|
Instead the display provides a viewport into the framebuffer. An
|
556 |
|
|
ioctl
|
557 |
|
|
can be used to move the viewport.
|
558 |
|
|
|
559 |
|
|
|
560 |
|
|
|
561 |
|
|
CYG_FB_FLAGS0_DOUBLE_BUFFER
|
562 |
|
|
|
563 |
|
|
The display does not show the current contents of the framebuffer, so
|
564 |
|
|
the results of drawing into the framebuffer are not immediately
|
565 |
|
|
visible. Instead higher-level code needs to perform an explicit
|
566 |
|
|
synch operation to
|
567 |
|
|
update the display.
|
568 |
|
|
|
569 |
|
|
|
570 |
|
|
|
571 |
|
|
CYG_FB_FLAGS0_PAGE_FLIPPING
|
572 |
|
|
|
573 |
|
|
The hardware supports two or more pages, each of width*height pixels,
|
574 |
|
|
only one of which is visible on the display. This allows higher-level
|
575 |
|
|
code to update one page without disturbing what is currently visible.
|
576 |
|
|
An
|
577 |
|
|
linkend="framebuf-control-ioctl-pageflip">ioctl
|
578 |
|
|
is used to switch the visible page.
|
579 |
|
|
|
580 |
|
|
|
581 |
|
|
|
582 |
|
|
CYG_FB_FLAGS0_BLANK
|
583 |
|
|
|
584 |
|
|
The display can be blanked
|
585 |
|
|
without affecting the framebuffer contents or settings.
|
586 |
|
|
|
587 |
|
|
|
588 |
|
|
|
589 |
|
|
CYG_FB_FLAGS0_BACKLIGHT
|
590 |
|
|
|
591 |
|
|
There is a backlight which can be
|
592 |
|
|
linkend="framebuf-control-ioctl-backlight">switched
|
593 |
|
|
on or off. Some hardware provides finer-grained control over the
|
594 |
|
|
backlight intensity.
|
595 |
|
|
|
596 |
|
|
|
597 |
|
|
|
598 |
|
|
CYG_FB_FLAGS0_MUST_BE_ON
|
599 |
|
|
|
600 |
|
|
Often it is desirable to perform some initialization such as clearing
|
601 |
|
|
the screen or setting the palette before the display is
|
602 |
|
|
linkend="framebuf-control-onoff">switched on, to avoid visual
|
603 |
|
|
noise. However not all hardware allows this. If this flag is set then
|
604 |
|
|
it is possible to access framebuffer memory and the palette before the
|
605 |
|
|
cyg_fb_on or CYG_FB_ON
|
606 |
|
|
operation. It may also be possible to perform some other operations
|
607 |
|
|
such as activating the backlight, but that is implementation-defined.
|
608 |
|
|
|
609 |
|
|
|
610 |
|
|
|
611 |
|
|
|
612 |
|
|
|
613 |
|
|
|
614 |
|
|
|
615 |
|
|
To allow for future expansion there are also flags1, flags2, and
|
616 |
|
|
flags3 fields. These may get used for encoding additional
|
617 |
|
|
ioctl functionality, support for hardware
|
618 |
|
|
acceleration, and similar features.
|
619 |
|
|
|
620 |
|
|
|
621 |
|
|
|
622 |
|
|
|
623 |
|
|
Linear Framebuffers
|
624 |
|
|
|
625 |
|
|
There are drawing primitives for writing and reading individual
|
626 |
|
|
pixels. However these involve a certain amount of arithmetic each time
|
627 |
|
|
to get from a position to an address within the frame buffer, plus
|
628 |
|
|
function call overhead if the function API is used, and this will slow
|
629 |
|
|
down graphics operations.
|
630 |
|
|
|
631 |
|
|
|
632 |
|
|
When the framebuffer device is known at compile-time and the macro API
|
633 |
|
|
is used then there are additional macros specifically for
|
634 |
|
|
linkend="framebuf-iterating">iterating over parts of the frame
|
635 |
|
|
buffer. These should prove very efficient for many graphics
|
636 |
|
|
operations. However if the device is selected at run-time then the
|
637 |
|
|
macros are not appropriate and code may want to manipulate framebuffer
|
638 |
|
|
memory directly. This is possible if two conditions are satisfied:
|
639 |
|
|
|
640 |
|
|
|
641 |
|
|
|
642 |
|
|
The CYG_FB_FLAGS0_LINEAR_FRAMEBUFFER flag must be
|
643 |
|
|
set. Otherwise framebuffer memory is either not directly accessible or
|
644 |
|
|
has a non-linear layout.
|
645 |
|
|
|
646 |
|
|
|
647 |
|
|
The CYG_FB_FLAGS0_DOUBLE_BUFFER flag must be clear.
|
648 |
|
|
An efficient double buffer synch operation requires knowing what part
|
649 |
|
|
of the framebuffer have been updated, and the various drawing
|
650 |
|
|
primitives will keep track of this. If higher-level code then starts
|
651 |
|
|
manipulating the framebuffer directly the synch operation may perform
|
652 |
|
|
only a partial update.
|
653 |
|
|
|
654 |
|
|
|
655 |
|
|
|
656 |
|
|
The base, stride, depth, width and height parameters, plus the
|
657 |
|
|
CYG_FB_FLAGS0_LE flag for 1bpp, 2bpp and 4bpp
|
658 |
|
|
devices, provide all the information needed to access framebuffer
|
659 |
|
|
memory. A linear framebuffer has pixel (0,0) at the base address.
|
660 |
|
|
Incrementing y means adding stride bytes to the pointer.
|
661 |
|
|
|
662 |
|
|
|
663 |
|
|
The base and stride parameters may be set even if
|
664 |
|
|
CYG_FB_FLAGS0_LINEAR_FRAMEBUFFER is clear. This can
|
665 |
|
|
be useful if for example the display is rotated in software from
|
666 |
|
|
landscape to portrait mode. However the meaning of these parameters
|
667 |
|
|
for non-linear framebuffers is implementation-defined.
|
668 |
|
|
|
669 |
|
|
|
670 |
|
|
|
671 |
|
|
|
672 |
|
|
|
673 |
|
|
|
674 |
|
|
|
675 |
|
|
|
676 |
|
|
|
677 |
|
|
Framebuffer Control Operations
|
678 |
|
|
|
679 |
|
|
|
680 |
|
|
Control Operations
|
681 |
|
|
managing a framebuffer
|
682 |
|
|
|
683 |
|
|
|
684 |
|
|
|
685 |
|
|
|
686 |
|
|
#include <cyg/io/framebuf.h>
|
687 |
|
|
|
688 |
|
|
|
689 |
|
|
int cyg_fb_on
|
690 |
|
|
cyg_fb* fbdev
|
691 |
|
|
|
692 |
|
|
|
693 |
|
|
int cyg_fb_off
|
694 |
|
|
cyg_fb* fbdev
|
695 |
|
|
|
696 |
|
|
|
697 |
|
|
int cyg_fb_ioctl
|
698 |
|
|
cyg_fb* fbdev
|
699 |
|
|
cyg_uint16 key
|
700 |
|
|
void* data
|
701 |
|
|
size_t* len
|
702 |
|
|
|
703 |
|
|
|
704 |
|
|
int CYG_FB_ON
|
705 |
|
|
FRAMEBUF
|
706 |
|
|
|
707 |
|
|
|
708 |
|
|
int CYG_FB_OFF
|
709 |
|
|
FRAMEBUF
|
710 |
|
|
|
711 |
|
|
|
712 |
|
|
int CYG_FB_IOCTL
|
713 |
|
|
FRAMEBUF
|
714 |
|
|
cyg_uint16 key
|
715 |
|
|
void* data
|
716 |
|
|
size_t* len
|
717 |
|
|
|
718 |
|
|
|
719 |
|
|
|
720 |
|
|
|
721 |
|
|
|
722 |
|
|
Description
|
723 |
|
|
|
724 |
|
|
The main operations on a framebuffer are drawing and colour
|
725 |
|
|
management. However on most hardware it is also necessary to switch
|
726 |
|
|
the display on before the
|
727 |
|
|
user can see anything, and application code should be able to control
|
728 |
|
|
when this happens. There are also miscellaneous operations such as
|
729 |
|
|
manipulating the backlight or moving the viewpoint. These do not
|
730 |
|
|
warrant dedicated functions, especially since the functionality will
|
731 |
|
|
only be available on some hardware, so an
|
732 |
|
|
linkend="framebuf-control-ioctl">ioctl
|
733 |
|
|
interface is used.
|
734 |
|
|
|
735 |
|
|
|
736 |
|
|
|
737 |
|
|
|
738 |
|
|
Switching the Display On or Off
|
739 |
|
|
|
740 |
|
|
With most hardware nothing will be visible until there is a call to
|
741 |
|
|
cyg_fb_on or an invocation of the
|
742 |
|
|
CYG_FB_ON macro. This will initialize the
|
743 |
|
|
framebuffer control circuitry, start sending the data signals to the
|
744 |
|
|
display unit, and switch on the display if necessary. The exact
|
745 |
|
|
initialization semantics are left to the framebuffer device driver. In
|
746 |
|
|
some cases the hardware may already be partially or fully initialized
|
747 |
|
|
by a static constructor or by boot code that ran before eCos.
|
748 |
|
|
|
749 |
|
|
|
750 |
|
|
There are some circumstances in which initialization can fail, and
|
751 |
|
|
this is indicated by a POSIX error code such as
|
752 |
|
|
ENODEV. An example would be plug and play hardware
|
753 |
|
|
where the framebuffer device is not detected at run-time. Another
|
754 |
|
|
example is hardware which can operate in several modes, with separate
|
755 |
|
|
cyg_fb structures for each mode, if the
|
756 |
|
|
hardware is already in use for a different mode. A return value of 0
|
757 |
|
|
indicates success.
|
758 |
|
|
|
759 |
|
|
|
760 |
|
|
Some but not all hardware allows the framebuffer memory and, if
|
761 |
|
|
present, the palette to be manipulated before the device is switched
|
762 |
|
|
on. That way the user does not see random noise on the screen during
|
763 |
|
|
system startup. The flag CYG_FB_FLAGS0_MUST_BE_ON
|
764 |
|
|
should be checked:
|
765 |
|
|
|
766 |
|
|
|
767 |
|
|
static void
|
768 |
|
|
init_screen(cyg_fb_colour background)
|
769 |
|
|
{
|
770 |
|
|
int result;
|
771 |
|
|
|
772 |
|
|
#if (! (CYG_FB_FLAGS0(FRAMEBUF) & CYG_FB_FLAGS0_MUST_BE_ON))
|
773 |
|
|
CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,
|
774 |
|
|
CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),
|
775 |
|
|
background);
|
776 |
|
|
#endif
|
777 |
|
|
|
778 |
|
|
result = CYG_FB_ON(FRAMEBUF);
|
779 |
|
|
if (0 != result) {
|
780 |
|
|
<handle unusual error condition>
|
781 |
|
|
}
|
782 |
|
|
|
783 |
|
|
#if (CYG_FB_FLAGS0(FRAMEBUF) & CYG_FB_FLAGS0_MUST_BE_ON)
|
784 |
|
|
CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,
|
785 |
|
|
CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),
|
786 |
|
|
background);
|
787 |
|
|
#endif
|
788 |
|
|
}
|
789 |
|
|
|
790 |
|
|
|
791 |
|
|
Obviously if the application has already manipulated framebuffer
|
792 |
|
|
memory or the palette but then the cyg_fb_on
|
793 |
|
|
operation fails, the system is left in an undefined state.
|
794 |
|
|
|
795 |
|
|
|
796 |
|
|
It is also possible to switch a framebuffer device off, using the
|
797 |
|
|
function cyg_fb_off or the macro
|
798 |
|
|
CYG_FB_OFF, although this functionality is rarely
|
799 |
|
|
used in embedded systems. The exact semantics of switching a device
|
800 |
|
|
off are implementation-defined, but typically it involves shutting
|
801 |
|
|
down the display, stopping the data signals to the display, and
|
802 |
|
|
halting the control circuitry. The framebuffer memory and the palette
|
803 |
|
|
are left in an undefined state, and application code should assume
|
804 |
|
|
that both need full reinitializing when the device is switched back
|
805 |
|
|
on. Some hardware may also provide a
|
806 |
|
|
linkend="framebuf-control-ioctl-blank">blank operation which
|
807 |
|
|
typically just manipulates the display, not the whole framebuffer
|
808 |
|
|
device. Normally cyg_fb_on returns 0. The API
|
809 |
|
|
allows for a POSIX error code as with cyg_fb_on,
|
810 |
|
|
but switching a device off is not an operation that is likely to fail.
|
811 |
|
|
|
812 |
|
|
|
813 |
|
|
If a framebuffer device can operate in several modes, represented by
|
814 |
|
|
several cyg_fb structures and macro
|
815 |
|
|
identifiers, then switching modes requires turning the current device
|
816 |
|
|
off before turning the next one one.
|
817 |
|
|
|
818 |
|
|
|
819 |
|
|
|
820 |
|
|
|
821 |
|
|
Miscellaneous Control Operations
|
822 |
|
|
|
823 |
|
|
Some hardware functionality such as an LCD panel backlight is common
|
824 |
|
|
but not universal. Supporting these does not warrant dedicated
|
825 |
|
|
functions. Instead a catch-all ioctl interface is
|
826 |
|
|
provided, with the arguments just passed straight to the device
|
827 |
|
|
driver. This approach also allows for future expansion and for
|
828 |
|
|
device-specific operations. cyg_fb_ioctl and
|
829 |
|
|
CYG_FB_IOCTL take four arguments: a
|
830 |
|
|
cyg_fb structure or framebuffer identifier; a
|
831 |
|
|
key that specifies the operation to be performed; an arbitrary
|
832 |
|
|
pointer, which should usually be a pointer to a data structure
|
833 |
|
|
specific to the key; and a length field. Key values from 0 to 0x7fff
|
834 |
|
|
are generic. Key values from 0x8000 onwards are reserved for the
|
835 |
|
|
individual framebuffer device drivers, for device-specific
|
836 |
|
|
functionality. The length field should be set to the size of the data
|
837 |
|
|
structure, and may get updated by the device driver.
|
838 |
|
|
|
839 |
|
|
|
840 |
|
|
With most ioctl operations the device can indicate whether or not it
|
841 |
|
|
supports the functionality by one of the flags, for example:
|
842 |
|
|
|
843 |
|
|
|
844 |
|
|
void
|
845 |
|
|
backlight_off(cyg_fb* fb)
|
846 |
|
|
{
|
847 |
|
|
if (fb->fb_flags0 & CYG_FB_FLAGS0_BACKLIGHT) {
|
848 |
|
|
cyg_fb_ioctl_backlight new_setting;
|
849 |
|
|
size_t len = sizeof(cyg_fb_ioctl_backlight);
|
850 |
|
|
int result;
|
851 |
|
|
|
852 |
|
|
new_setting.fbbl_current = 0;
|
853 |
|
|
result = cyg_fb_ioctl(fb, CYG_FB_IOCTL_BACKLIGHT_SET,
|
854 |
|
|
&new_setting, &len);
|
855 |
|
|
if (0 != result) {
|
856 |
|
|
…
|
857 |
|
|
}
|
858 |
|
|
}
|
859 |
|
|
}
|
860 |
|
|
|
861 |
|
|
|
862 |
|
|
The operation returns zero for success or a POSIX error code on
|
863 |
|
|
failure, for example ENOSYS if the device driver
|
864 |
|
|
does not implement the requested functionality.
|
865 |
|
|
|
866 |
|
|
|
867 |
|
|
|
868 |
|
|
Viewport
|
869 |
|
|
|
870 |
|
|
# define CYG_FB_IOCTL_VIEWPORT_GET_POSITION 0x0100
|
871 |
|
|
# define CYG_FB_IOCTL_VIEWPORT_SET_POSITION 0x0101
|
872 |
|
|
|
873 |
|
|
typedef struct cyg_fb_ioctl_viewport {
|
874 |
|
|
cyg_ucount16 fbvp_x; // position of top-left corner of the viewport within
|
875 |
|
|
cyg_ucount16 fbvp_y; // the framebuffer
|
876 |
|
|
cyg_ucount16 fbvp_when; // set-only, now or vert retrace
|
877 |
|
|
} cyg_fb_ioctl_viewport;
|
878 |
|
|
|
879 |
|
|
|
880 |
|
|
On some targets the framebuffer device has a higher resolution than
|
881 |
|
|
the display. Only a subset of the pixels, the viewport, is currently
|
882 |
|
|
visible. Application code can exploit this functionality to achieve
|
883 |
|
|
certain effects, for example smooth scrolling. Framebuffers which
|
884 |
|
|
support this functionality will have the
|
885 |
|
|
CYG_FB_FLAGS0_VIEWPORT flag set. The viewport
|
886 |
|
|
dimensions are available as additional
|
887 |
|
|
linkend="framebuf-parameters">parameters to the normal
|
888 |
|
|
framebuffer width and height.
|
889 |
|
|
|
890 |
|
|
|
891 |
|
|
The current position of the viewport can be obtained using an
|
892 |
|
|
CYG_FB_IOCTL_VIEWPORT_GET_POSITION ioctl operation.
|
893 |
|
|
The data argument should be a pointer to a
|
894 |
|
|
cyg_fb_ioctl_viewport structure. On return
|
895 |
|
|
the fbvp_x and
|
896 |
|
|
fbvp_y fields will be filled in. To move
|
897 |
|
|
the viewport use CYG_FB_IOCTL_VIEWPORT_SET_POSITION
|
898 |
|
|
with fbvp_x and
|
899 |
|
|
fbvp_y set to the top left corner of the
|
900 |
|
|
new viewport within the framebuffer, and
|
901 |
|
|
fbvp_when set to either
|
902 |
|
|
CYG_FB_UPDATE_NOW or
|
903 |
|
|
CYG_FB_UPDATE_VERTICAL_RETRACE. If the device
|
904 |
|
|
driver cannot easily synchronize to a vertical retrace period then
|
905 |
|
|
this last field is ignored.
|
906 |
|
|
|
907 |
|
|
|
908 |
|
|
void
|
909 |
|
|
move_viewport(cyg_fb* fb, int dx, int dy)
|
910 |
|
|
{
|
911 |
|
|
#ifdef CYGHWR_IO_FRAMEBUF_FUNCTIONALITY_VIEWPORT
|
912 |
|
|
cyg_fb_ioctl_viewport viewport;
|
913 |
|
|
int len = sizeof(cyg_fb_ioctl_viewport);
|
914 |
|
|
int result;
|
915 |
|
|
|
916 |
|
|
result = cyg_fb_ioctl(fb, CYG_FB_IOCTL_VIEWPORT_GET_POSITION,
|
917 |
|
|
&viewport, &len);
|
918 |
|
|
if (result != 0) {
|
919 |
|
|
…
|
920 |
|
|
}
|
921 |
|
|
if (((int)viewport.fbvp_x + dx) < 0) {
|
922 |
|
|
viewport.fbvp_x = 0;
|
923 |
|
|
} else if ((viewport.fbvp_x + dx + fb->fb_viewport_width) > fb->fb_width) {
|
924 |
|
|
viewport.fbvp_x = fb->fb_width - fb->fb_viewport_width;
|
925 |
|
|
} else {
|
926 |
|
|
viewport.fbvp_x += dx;
|
927 |
|
|
}
|
928 |
|
|
if (((int)viewport.fbvp_y + dy) < 0) {
|
929 |
|
|
viewport.fbvp_y = 0;
|
930 |
|
|
} else if ((viewport.fbvp_y + dy + fb->fb_viewport_height) > fb->fb_height) {
|
931 |
|
|
viewport.fbvp_y = fb->fb_height - fb->fb_viewport_height;
|
932 |
|
|
} else {
|
933 |
|
|
viewport.fbvp_y += dy;
|
934 |
|
|
}
|
935 |
|
|
result = cyg_fb_ioctl(fb, CYG_FB_IOCTL_VIEWPORT_SET_POSITION,
|
936 |
|
|
&viewport, &len);
|
937 |
|
|
if (result != 0) {
|
938 |
|
|
…
|
939 |
|
|
}
|
940 |
|
|
#else
|
941 |
|
|
CYG_UNUSED_PARAM(cyg_fb*, fb);
|
942 |
|
|
CYG_UNUSED_PARAM(int, dx);
|
943 |
|
|
CYG_UNUSED_PARAM(int, dy);
|
944 |
|
|
#endif
|
945 |
|
|
}
|
946 |
|
|
|
947 |
|
|
|
948 |
|
|
If an attempt is made to move the viewport beyond the boundaries of
|
949 |
|
|
the framebuffer then the resulting behaviour is undefined. Some
|
950 |
|
|
hardware may behave reasonably, wrapping around as appropriate, but
|
951 |
|
|
portable code cannot assume this. The above code fragment is careful
|
952 |
|
|
to clip the viewport to the framebuffer dimensions.
|
953 |
|
|
|
954 |
|
|
|
955 |
|
|
|
956 |
|
|
|
957 |
|
|
Page Flipping
|
958 |
|
|
|
959 |
|
|
# define CYG_FB_IOCTL_PAGE_FLIPPING_GET_PAGES 0x0200
|
960 |
|
|
# define CYG_FB_IOCTL_PAGE_FLIPPING_SET_PAGES 0x0201
|
961 |
|
|
|
962 |
|
|
typedef struct cyg_fb_ioctl_page_flip {
|
963 |
|
|
cyg_uint32 fbpf_number_pages;
|
964 |
|
|
cyg_uint32 fbpf_visible_page;
|
965 |
|
|
cyg_uint32 fbpf_drawable_page;
|
966 |
|
|
cyg_ucount16 fbpf_when; // set-only, now or vert retrace
|
967 |
|
|
} cyg_fb_ioctl_page_flip;
|
968 |
|
|
|
969 |
|
|
|
970 |
|
|
On some targets the framebuffer has enough memory for several pages,
|
971 |
|
|
only one of which is visible at a time. This allows the application
|
972 |
|
|
to draw into one page while displaying another. Once drawing is
|
973 |
|
|
complete the display is flipped to the newly drawn page, and the
|
974 |
|
|
previously displayed page is now available for updating. This
|
975 |
|
|
technique is used for smooth animation, especially in games. The flag
|
976 |
|
|
CYG_FB_FLAGS0_PAGE_FLIPPING indicates support for
|
977 |
|
|
this functionality.
|
978 |
|
|
|
979 |
|
|
|
980 |
|
|
CYG_FB_IOCTL_PAGE_FLIPPING_GET_PAGES can be used to
|
981 |
|
|
get the current settings of the page flipping support. The data
|
982 |
|
|
argument should be a pointer to a
|
983 |
|
|
cyg_fb_ioctl_page_flip structure. The
|
984 |
|
|
resulting fbpf_number_pages field indicates
|
985 |
|
|
the total number of pages available: 2 is common, but more pages are
|
986 |
|
|
possible. fbpf_visible_page gives the page
|
987 |
|
|
that is currently visible to the user, and will be between 0 and
|
988 |
|
|
(fbpf_number_pages - 1).
|
989 |
|
|
Similarly fbpf_drawable_page gives the page
|
990 |
|
|
that is currently visible. It is implementation-defined whether or not
|
991 |
|
|
the visible and drawable page can be the same one.
|
992 |
|
|
|
993 |
|
|
|
994 |
|
|
CYG_FB_IOCTL_PAGE_FLIPPING_SET_PAGES can be used to
|
995 |
|
|
change the visible and drawable page. The
|
996 |
|
|
fbpf_number_pages field is ignored.
|
997 |
|
|
fbpf_visible_page and
|
998 |
|
|
fbpf_drawable_page give the new settings.
|
999 |
|
|
fbpf_when should be one of
|
1000 |
|
|
CYG_FB_UPDATE_NOW or
|
1001 |
|
|
CYG_FB_UPDATE_VERTICAL_RETRACE, but may be ignored
|
1002 |
|
|
by some device drivers.
|
1003 |
|
|
|
1004 |
|
|
|
1005 |
|
|
#if !(CYG_FB_FLAGS0(FRAMEBUF) & CYG_FB_FLAGS0_PAGE_FLIPPING)
|
1006 |
|
|
# error Current framebuffer device does not support page flipping
|
1007 |
|
|
#endif
|
1008 |
|
|
|
1009 |
|
|
static cyg_uint32 current_visible = 0;
|
1010 |
|
|
|
1011 |
|
|
static void
|
1012 |
|
|
page_flip_init(cyg_fb_colour background)
|
1013 |
|
|
{
|
1014 |
|
|
cyg_fb_ioctl_page_flip flip;
|
1015 |
|
|
size_t len = sizeof(cyg_fb_ioctl_page_flip);
|
1016 |
|
|
|
1017 |
|
|
flip.fbpf_visible_page = current_visible;
|
1018 |
|
|
flip.fbpf_drawable_page = 1 - current_visible;
|
1019 |
|
|
flip.fbpf_when = CYG_FB_UPDATE_NOW;
|
1020 |
|
|
CYG_FB_IOCTL(FRAMEBUF, CYG_FB_IOCTL_PAGE_FLIPPING_SET_PAGES,
|
1021 |
|
|
&flip, &len);
|
1022 |
|
|
CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,
|
1023 |
|
|
CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),
|
1024 |
|
|
background);
|
1025 |
|
|
flip.fbpf_visible_page = 1 - current_visible;
|
1026 |
|
|
flip.fbpf_drawable_page = current_visible;
|
1027 |
|
|
CYG_FB_IOCTL(FRAMEBUF, CYG_FB_IOCTL_PAGE_FLIPPING_SET_PAGES,
|
1028 |
|
|
&flip, &len);
|
1029 |
|
|
CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,
|
1030 |
|
|
CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),
|
1031 |
|
|
background);
|
1032 |
|
|
current_visible = 1 - current_visible;
|
1033 |
|
|
}
|
1034 |
|
|
|
1035 |
|
|
static void
|
1036 |
|
|
page_flip_toggle(void)
|
1037 |
|
|
{
|
1038 |
|
|
cyg_fb_ioctl_page_flip flip;
|
1039 |
|
|
size_t len = sizeof(cyg_fb_ioctl_page_flip);
|
1040 |
|
|
|
1041 |
|
|
flip.fbpf_visible_page = 1 - current_visible;
|
1042 |
|
|
flip.fbpf_drawable_page = current_visible;
|
1043 |
|
|
CYG_FB_IOCTL(FRAMEBUF, CYG_FB_IOCTL_PAGE_FLIPPING_SET_PAGES,
|
1044 |
|
|
&flip, &len);
|
1045 |
|
|
current_visible = 1 - current_visible;
|
1046 |
|
|
}
|
1047 |
|
|
|
1048 |
|
|
|
1049 |
|
|
A page flip typically just changes a couple of pointers within the
|
1050 |
|
|
hardware and device driver. No attempt is made to synchronize the
|
1051 |
|
|
contents of the pages, that is left to higher-level code.
|
1052 |
|
|
|
1053 |
|
|
|
1054 |
|
|
|
1055 |
|
|
|
1056 |
|
|
Blanking the Screen
|
1057 |
|
|
|
1058 |
|
|
# define CYG_FB_IOCTL_BLANK_GET 0x0300
|
1059 |
|
|
# define CYG_FB_IOCTL_BLANK_SET 0x0301
|
1060 |
|
|
|
1061 |
|
|
typedef struct cyg_fb_ioctl_blank {
|
1062 |
|
|
cyg_bool fbbl_on;
|
1063 |
|
|
} cyg_fb_ioctl_blank;
|
1064 |
|
|
|
1065 |
|
|
|
1066 |
|
|
Some hardware allows the display to be switched off or blanked without
|
1067 |
|
|
shutting down the entire framebuffer device, greatly reducing power
|
1068 |
|
|
consumption. The current blanking state can be obtained using
|
1069 |
|
|
CYG_FB_IOCTL_BLANK_GET and the state can be updated
|
1070 |
|
|
using CYG_FB_IOCTL_BLANK_SET. The data argument
|
1071 |
|
|
should be a pointer to a cyg_fb_ioctl_blank
|
1072 |
|
|
structure. Support for this functionality is indicated by the
|
1073 |
|
|
CYG_FB_FLAGS0_BLANK flag.
|
1074 |
|
|
|
1075 |
|
|
|
1076 |
|
|
static cyg_bool
|
1077 |
|
|
display_blanked(cyg_fb_* fb)
|
1078 |
|
|
{
|
1079 |
|
|
cyg_fb_ioctl_blank blank;
|
1080 |
|
|
size_t len = sizeof(cyg_fb_ioctl_blank);
|
1081 |
|
|
|
1082 |
|
|
if (! (fb->fb_flags0 & CYG_FB_FLAGS0_BLANK)) {
|
1083 |
|
|
return false;
|
1084 |
|
|
}
|
1085 |
|
|
(void) cyg_fb_ioctl(fb, CYG_FB_IOCTL_BLANK_GET, &blank, &len);
|
1086 |
|
|
return !blank.fbbl_on;
|
1087 |
|
|
}
|
1088 |
|
|
|
1089 |
|
|
|
1090 |
|
|
|
1091 |
|
|
|
1092 |
|
|
Controlling the Backlight
|
1093 |
|
|
|
1094 |
|
|
# define CYG_FB_IOCTL_BACKLIGHT_GET 0x0400
|
1095 |
|
|
# define CYG_FB_IOCTL_BACKLIGHT_SET 0x0401
|
1096 |
|
|
|
1097 |
|
|
typedef struct cyg_fb_ioctl_backlight {
|
1098 |
|
|
cyg_ucount32 fbbl_current;
|
1099 |
|
|
cyg_ucount32 fbbl_max;
|
1100 |
|
|
} cyg_fb_ioctl_backlight;
|
1101 |
|
|
|
1102 |
|
|
|
1103 |
|
|
Many LCD panels provide some sort of backlight, making the display
|
1104 |
|
|
easier to read at the cost of increased power consumption. Support for
|
1105 |
|
|
this is indicated by the CYG_FB_FLAGS0_BACKLIGHT
|
1106 |
|
|
flag. CYG_FB_IOCTL_BACKLIGHT_GET can be used to get
|
1107 |
|
|
both the current setting and the maximum value. If the maximum is 1
|
1108 |
|
|
then the backlight can only be switched on or off. Otherwise it is
|
1109 |
|
|
possible to control the intensity.
|
1110 |
|
|
|
1111 |
|
|
|
1112 |
|
|
static void
|
1113 |
|
|
set_backlight_50_percent(void)
|
1114 |
|
|
{
|
1115 |
|
|
#if (CYG_FB_FLAGS0(FRAMEBUF) & CYG_FB_FLAGS0_BACKLIGHT)
|
1116 |
|
|
cyg_fb_ioctl_backlight backlight;
|
1117 |
|
|
size_t len = sizeof(cyg_fb_ioctl_backlight);
|
1118 |
|
|
|
1119 |
|
|
CYG_FB_IOCTL(FRAMEBUF, CYG_FB_IOCTL_BACKLIGHT_GET, &backlight, &len);
|
1120 |
|
|
backlight.fbbl_current = (backlight.fbbl_max + 1) >> 1;
|
1121 |
|
|
CYG_FB_IOCTL(FRAMEBUF, CYG_FB_IOCTL_BACKLIGHT_SET, &backlight, &len);
|
1122 |
|
|
#endif
|
1123 |
|
|
}
|
1124 |
|
|
|
1125 |
|
|
|
1126 |
|
|
|
1127 |
|
|
|
1128 |
|
|
|
1129 |
|
|
|
1130 |
|
|
|
1131 |
|
|
|
1132 |
|
|
|
1133 |
|
|
|
1134 |
|
|
|
1135 |
|
|
Framebuffer Colours
|
1136 |
|
|
|
1137 |
|
|
|
1138 |
|
|
Colours
|
1139 |
|
|
formats and palette management
|
1140 |
|
|
|
1141 |
|
|
|
1142 |
|
|
|
1143 |
|
|
|
1144 |
|
|
#include <cyg/io/framebuf.h>
|
1145 |
|
|
|
1146 |
|
|
typedef struct cyg_fb {
|
1147 |
|
|
cyg_ucount16 fb_depth;
|
1148 |
|
|
cyg_ucount16 fb_format;
|
1149 |
|
|
cyg_uint32 fb_flags0;
|
1150 |
|
|
…
|
1151 |
|
|
} cyg_fb;
|
1152 |
|
|
|
1153 |
|
|
extern const cyg_uint8 cyg_fb_palette_ega[16 * 3];
|
1154 |
|
|
extern const cyg_uint8 cyg_fb_palette_vga[256 * 3];
|
1155 |
|
|
|
1156 |
|
|
#define CYG_FB_DEFAULT_PALETTE_BLACK 0x00
|
1157 |
|
|
#define CYG_FB_DEFAULT_PALETTE_BLUE 0x01
|
1158 |
|
|
#define CYG_FB_DEFAULT_PALETTE_GREEN 0x02
|
1159 |
|
|
#define CYG_FB_DEFAULT_PALETTE_CYAN 0x03
|
1160 |
|
|
#define CYG_FB_DEFAULT_PALETTE_RED 0x04
|
1161 |
|
|
#define CYG_FB_DEFAULT_PALETTE_MAGENTA 0x05
|
1162 |
|
|
#define CYG_FB_DEFAULT_PALETTE_BROWN 0x06
|
1163 |
|
|
#define CYG_FB_DEFAULT_PALETTE_LIGHTGREY 0x07
|
1164 |
|
|
#define CYG_FB_DEFAULT_PALETTE_LIGHTGRAY 0x07
|
1165 |
|
|
#define CYG_FB_DEFAULT_PALETTE_DARKGREY 0x08
|
1166 |
|
|
#define CYG_FB_DEFAULT_PALETTE_DARKGRAY 0x08
|
1167 |
|
|
#define CYG_FB_DEFAULT_PALETTE_LIGHTBLUE 0x09
|
1168 |
|
|
#define CYG_FB_DEFAULT_PALETTE_LIGHTGREEN 0x0A
|
1169 |
|
|
#define CYG_FB_DEFAULT_PALETTE_LIGHTCYAN 0x0B
|
1170 |
|
|
#define CYG_FB_DEFAULT_PALETTE_LIGHTRED 0x0C
|
1171 |
|
|
#define CYG_FB_DEFAULT_PALETTE_LIGHTMAGENTA 0x0D
|
1172 |
|
|
#define CYG_FB_DEFAULT_PALETTE_YELLOW 0x0E
|
1173 |
|
|
#define CYG_FB_DEFAULT_PALETTE_WHITE 0x0F
|
1174 |
|
|
|
1175 |
|
|
|
1176 |
|
|
cyg_ucount16 CYG_FB_FORMAT
|
1177 |
|
|
framebuf
|
1178 |
|
|
|
1179 |
|
|
|
1180 |
|
|
void cyg_fb_read_palette
|
1181 |
|
|
cyg_fb* fb
|
1182 |
|
|
cyg_ucount32 first
|
1183 |
|
|
cyg_ucount32 count
|
1184 |
|
|
void* data
|
1185 |
|
|
|
1186 |
|
|
|
1187 |
|
|
void cyg_fb_write_palette
|
1188 |
|
|
cyg_fb* fb
|
1189 |
|
|
cyg_ucount32 first
|
1190 |
|
|
cyg_ucount32 count
|
1191 |
|
|
const void* data
|
1192 |
|
|
cyg_ucount16 when
|
1193 |
|
|
|
1194 |
|
|
|
1195 |
|
|
cyg_fb_colour cyg_fb_make_colour
|
1196 |
|
|
cyg_fb* fb
|
1197 |
|
|
cyg_ucount8 r
|
1198 |
|
|
cyg_ucount8 g
|
1199 |
|
|
cyg_ucount8 b
|
1200 |
|
|
|
1201 |
|
|
|
1202 |
|
|
void cyg_fb_break_colour
|
1203 |
|
|
cyg_fb* fb
|
1204 |
|
|
cyg_fb_colour colour
|
1205 |
|
|
cyg_ucount8* r
|
1206 |
|
|
cyg_ucount8* g
|
1207 |
|
|
cyg_ucount8* b
|
1208 |
|
|
|
1209 |
|
|
|
1210 |
|
|
void CYG_FB_READ_PALETTE
|
1211 |
|
|
FRAMEBUF
|
1212 |
|
|
cyg_ucount32 first
|
1213 |
|
|
cyg_ucount32 count
|
1214 |
|
|
void* data
|
1215 |
|
|
|
1216 |
|
|
|
1217 |
|
|
void CYG_FB_WRITE_PALETTE
|
1218 |
|
|
FRAMEBUF
|
1219 |
|
|
cyg_ucount32 first
|
1220 |
|
|
cyg_ucount32 count
|
1221 |
|
|
const void* data
|
1222 |
|
|
cyg_ucount16 when
|
1223 |
|
|
|
1224 |
|
|
|
1225 |
|
|
cyg_fb_colour CYG_FB_MAKE_COLOUR
|
1226 |
|
|
FRAMEBUF
|
1227 |
|
|
cyg_ucount8 r
|
1228 |
|
|
cyg_ucount8 g
|
1229 |
|
|
cyg_ucount8 b
|
1230 |
|
|
|
1231 |
|
|
|
1232 |
|
|
void CYG_FB_BREAK_COLOUR
|
1233 |
|
|
FRAMEBUF
|
1234 |
|
|
cyg_fb_colour colour
|
1235 |
|
|
cyg_ucount8* r
|
1236 |
|
|
cyg_ucount8* g
|
1237 |
|
|
cyg_ucount8* b
|
1238 |
|
|
|
1239 |
|
|
|
1240 |
|
|
|
1241 |
|
|
|
1242 |
|
|
|
1243 |
|
|
Description
|
1244 |
|
|
|
1245 |
|
|
Managing colours can be one of the most difficult aspects of writing
|
1246 |
|
|
graphics code, especially if that code is intended to be portable to
|
1247 |
|
|
many different platforms. Displays can vary from 1bpp monochrome, via
|
1248 |
|
|
2bpp and 4bpp greyscale, through 4bpp and 8bpp paletted, and up to
|
1249 |
|
|
16bpp and 32bpp true colour - and those are just the more common
|
1250 |
|
|
scenarios. The various drawing
|
1251 |
|
|
primitives like cyg_fb_write_pixel work in
|
1252 |
|
|
terms of cyg_fb_colour values, usually an unsigned
|
1253 |
|
|
integer. Exactly how the hardware interprets a
|
1254 |
|
|
cyg_fb_colour depends on the format.
|
1255 |
|
|
|
1256 |
|
|
|
1257 |
|
|
|
1258 |
|
|
|
1259 |
|
|
Colour Formats
|
1260 |
|
|
|
1261 |
|
|
There are a number of ways of finding out how these values will be
|
1262 |
|
|
interpreted by the hardware:
|
1263 |
|
|
|
1264 |
|
|
|
1265 |
|
|
|
1266 |
|
|
The CYG_FB_FLAGS0_TRUE_COLOUR flag is set for all
|
1267 |
|
|
true colour displays. The format parameter can be examined for more
|
1268 |
|
|
details but this is not usually necessary. Instead code can use
|
1269 |
|
|
|
1270 |
|
|
linkend="framebuf-colour-true">cyg_fb_make_colour
|
1271 |
|
|
or
|
1272 |
|
|
linkend="framebuf-colour-true">CYG_FB_MAKE_COLOUR
|
1273 |
|
|
to construct a cyg_fb_colour value from red, green and
|
1274 |
|
|
blue components.
|
1275 |
|
|
|
1276 |
|
|
|
1277 |
|
|
If the CYG_FB_FLAGS0_WRITEABLE_PALETTE flag is set
|
1278 |
|
|
then a cyg_fb_colour value is an index into a lookup
|
1279 |
|
|
table known as the palette, and this table contains red, green and
|
1280 |
|
|
blue components. The size of the palette is determined by the display
|
1281 |
|
|
depth, so 16 entries for a 4bpp display and 256 entries for an 8bpp
|
1282 |
|
|
display. Application code or a graphics library can
|
1283 |
|
|
linkend="framebuf-colour-palette">install its own palette so
|
1284 |
|
|
can control exactly what colour each cyg_fb_colour value
|
1285 |
|
|
corresponds to. Alternatively there is support for installing a
|
1286 |
|
|
default palette.
|
1287 |
|
|
|
1288 |
|
|
|
1289 |
|
|
If CYG_FB_FLAGS0_PALETTE is set but
|
1290 |
|
|
CYG_FB_FLAGS0_WRITEABLE_PALETTE is clear then the
|
1291 |
|
|
hardware uses a fixed palette. There is no easy way for portable
|
1292 |
|
|
software to handle this case. The palette can be read at run-time,
|
1293 |
|
|
allowing the application's desired colours to be mapped to whichever
|
1294 |
|
|
palette entry provides the best match. However normally it will be
|
1295 |
|
|
necessary to write code specifically for the fixed palette.
|
1296 |
|
|
|
1297 |
|
|
|
1298 |
|
|
Otherwise the display is monochrome or greyscale, depending on the
|
1299 |
|
|
depth. There are still variations, for example on a monochrome display
|
1300 |
|
|
colour 0 can be either white or black.
|
1301 |
|
|
|
1302 |
|
|
|
1303 |
|
|
|
1304 |
|
|
As an alternative or to provide additional information, the exact
|
1305 |
|
|
colour format is provided by the fb_format
|
1306 |
|
|
field of the cyg_fb structure or by the
|
1307 |
|
|
CYG_FB_FORMAT macro. It can be one of the
|
1308 |
|
|
following (more entries may be added in future):
|
1309 |
|
|
|
1310 |
|
|
|
1311 |
|
|
|
1312 |
|
|
CYG_FB_FORMAT_1BPP_MONO_0_BLACK
|
1313 |
|
|
|
1314 |
|
|
simple 1bpp monochrome display, with 0 as black or the darker of the
|
1315 |
|
|
two colours, and 1 as white or the ligher colour.
|
1316 |
|
|
|
1317 |
|
|
|
1318 |
|
|
|
1319 |
|
|
CYG_FB_FORMAT_1BPP_MONO_0_WHITE
|
1320 |
|
|
|
1321 |
|
|
simple 1bpp monochrome display, with 0 as white or the lighter of the
|
1322 |
|
|
two colours, and 1 as black or the darker colour.
|
1323 |
|
|
|
1324 |
|
|
|
1325 |
|
|
|
1326 |
|
|
CYG_FB_FORMAT_1BPP_PAL888
|
1327 |
|
|
|
1328 |
|
|
a 1bpp display which cannot easily be described as monochrome. This is
|
1329 |
|
|
unusual and not readily supported by portable code. It can happen if
|
1330 |
|
|
the framebuffer normally runs at a higher depth, for example 4bpp or
|
1331 |
|
|
8bpp paletted, but is run at only 1bpp to save memory. Hence only two
|
1332 |
|
|
of the palette entries are used, but can be set to arbitrary colours.
|
1333 |
|
|
The palette may be read-only or read-write.
|
1334 |
|
|
|
1335 |
|
|
|
1336 |
|
|
|
1337 |
|
|
CYG_FB_FORMAT_2BPP_GREYSCALE_0_BLACK
|
1338 |
|
|
|
1339 |
|
|
a 2bpp display offering four shades of grey, with 0 as black or the
|
1340 |
|
|
darkest of the four shades, and 3 as white or the lightest.
|
1341 |
|
|
|
1342 |
|
|
|
1343 |
|
|
|
1344 |
|
|
CYG_FB_FORMAT_2BPP_GREYSCALE_0_WHITE
|
1345 |
|
|
|
1346 |
|
|
a 2bpp display offering four shades of grey, with 0 as white or the
|
1347 |
|
|
lightest of the four shades, and 3 as black or the darkest.
|
1348 |
|
|
|
1349 |
|
|
|
1350 |
|
|
|
1351 |
|
|
CYG_FB_FORMAT_2BPP_PAL888
|
1352 |
|
|
|
1353 |
|
|
a 2bpp display which cannot easily be described as greyscale, for
|
1354 |
|
|
example providing black, red, blue and white as the four colours.
|
1355 |
|
|
This is unusual and not readily supported by portable code. It can
|
1356 |
|
|
happen if the framebuffer normally runs at a higher depth, for example
|
1357 |
|
|
4bpp or 8bpp paletted, but is run at only 2bpp to save memory. Hence
|
1358 |
|
|
only four of the palette entries are used, but can be set to arbitrary
|
1359 |
|
|
colours. The palette may be read-only or read-write.
|
1360 |
|
|
|
1361 |
|
|
|
1362 |
|
|
|
1363 |
|
|
CYG_FB_FORMAT_4BPP_GREYSCALE_0_BLACK
|
1364 |
|
|
|
1365 |
|
|
a 4bpp display offering sixteen shades of grey, with 0 as black or the
|
1366 |
|
|
darkest of the 16 shades, and 15 as white or the lighest.
|
1367 |
|
|
|
1368 |
|
|
|
1369 |
|
|
|
1370 |
|
|
CYG_FB_FORMAT_4BPP_GREYSCALE_0_WHITE
|
1371 |
|
|
|
1372 |
|
|
a 4bpp display offering sixteen shades of grey, with 0 as white or the
|
1373 |
|
|
lightest of the 16 shades, and 15 as black or the darkest.
|
1374 |
|
|
|
1375 |
|
|
|
1376 |
|
|
|
1377 |
|
|
CYG_FB_FORMAT_4BPP_PAL888
|
1378 |
|
|
|
1379 |
|
|
a 4bpp paletted display, allowing for 16 different colours on screen
|
1380 |
|
|
at the same time. The palette may be read-only or read-write.
|
1381 |
|
|
|
1382 |
|
|
|
1383 |
|
|
|
1384 |
|
|
CYG_FB_FORMAT_8BPP_PAL888
|
1385 |
|
|
|
1386 |
|
|
an 8bpp paletted display, allowing for 256 different colours on screen
|
1387 |
|
|
at the same time. The palette may be read-only or read-write.
|
1388 |
|
|
|
1389 |
|
|
|
1390 |
|
|
|
1391 |
|
|
CYG_FB_FORMAT_8BPP_TRUE_332
|
1392 |
|
|
|
1393 |
|
|
an 8bpp true colour display, with three bits (eight levels) of red and
|
1394 |
|
|
green intensity and two bits (four levels) of blue intensity.
|
1395 |
|
|
|
1396 |
|
|
|
1397 |
|
|
|
1398 |
|
|
CYG_FB_FORMAT_16BPP_TRUE_565
|
1399 |
|
|
|
1400 |
|
|
a 16bpp true colour display with 5 bits each for red and blue and 6
|
1401 |
|
|
bits for green.
|
1402 |
|
|
|
1403 |
|
|
|
1404 |
|
|
|
1405 |
|
|
CYG_FB_FORMAT_16BPP_TRUE_555
|
1406 |
|
|
|
1407 |
|
|
a 16bpp true colour display with five bits each for red, green and
|
1408 |
|
|
blue, and one unused bit.
|
1409 |
|
|
|
1410 |
|
|
|
1411 |
|
|
|
1412 |
|
|
CYG_FB_FORMAT_32BPP_TRUE_0888
|
1413 |
|
|
|
1414 |
|
|
a 32bpp true colour display with eight bits each for red, green and
|
1415 |
|
|
blue and eight bits unused.
|
1416 |
|
|
|
1417 |
|
|
|
1418 |
|
|
|
1419 |
|
|
|
1420 |
|
|
For the true colour formats the format does not define exactly which
|
1421 |
|
|
bits in the pixel are used for which colour. Instead the
|
1422 |
|
|
cyg_fb_make_colour
|
1423 |
|
|
and cyg_fb_break_colour functions or the
|
1424 |
|
|
equivalent macros should be used to construct or decompose pixel
|
1425 |
|
|
values.
|
1426 |
|
|
|
1427 |
|
|
|
1428 |
|
|
|
1429 |
|
|
|
1430 |
|
|
Paletted Displays
|
1431 |
|
|
|
1432 |
|
|
Palettes are the common way of implementing low-end colour displays.
|
1433 |
|
|
There are two variants. A read-only palette provides a fixed set of
|
1434 |
|
|
colours and it is up to application code to use these colours
|
1435 |
|
|
appropriately. A read-write palette allows the application to select
|
1436 |
|
|
its own set of colours. Displays providing a read-write palette will
|
1437 |
|
|
have the CYG_FB_FLAGS0_WRITEABLE_PALETTE flag set
|
1438 |
|
|
in addition to CYG_FB_FLAGS0_PALETTE.
|
1439 |
|
|
|
1440 |
|
|
|
1441 |
|
|
Even if application code can install its own palette, many
|
1442 |
|
|
applications do not exploit this functionality and instead stick with
|
1443 |
|
|
a default. There are two standard palettes: the 16-entry PC EGA for
|
1444 |
|
|
4bpp displays; and the 256-entry PC VGA, a superset of the EGA one,
|
1445 |
|
|
for 8bpp displays. This package provides the data for both, in the
|
1446 |
|
|
form of arrays cyg_fb_palette_ega and
|
1447 |
|
|
cyg_fb_palette_vga, and 16
|
1448 |
|
|
#define's such as
|
1449 |
|
|
CYG_FB_DEFAULT_PALETTE_BLACK for the EGA colours
|
1450 |
|
|
and the first 16 VGA colours. By default device drivers for read-write
|
1451 |
|
|
paletted displays will install the appropriate default palette, but
|
1452 |
|
|
this can be suppressed using configuration option
|
1453 |
|
|
CYGFUN_IO_FRAMEBUF_INSTALL_DEFAULT_PALETTE. If a
|
1454 |
|
|
custom palette will be used then installing the default palette
|
1455 |
|
|
involves wasting 48 or 768 bytes of memory.
|
1456 |
|
|
|
1457 |
|
|
|
1458 |
|
|
It should be emphasized that displays vary widely. A colour such
|
1459 |
|
|
as CYG_FB_DEFAULT_PALETTE_YELLOW may appear rather
|
1460 |
|
|
differently on two different displays, although it should always be
|
1461 |
|
|
recognizable as yellow. Developers may wish to fine-tune the palette
|
1462 |
|
|
for specific hardware.
|
1463 |
|
|
|
1464 |
|
|
|
1465 |
|
|
The current palette can be retrieved using
|
1466 |
|
|
cyg_fb_read_palette or
|
1467 |
|
|
CYG_FB_READ_PALETTE. The
|
1468 |
|
|
first and count
|
1469 |
|
|
arguments control which palette entries should be retrieved. For
|
1470 |
|
|
example, to retrieve just palette entry 12
|
1471 |
|
|
first should be set to 12 and
|
1472 |
|
|
count should be set to 1. To retrieve all 256
|
1473 |
|
|
entries for an 8bpp display, first should be
|
1474 |
|
|
set to 0 and count should be set to 256. The
|
1475 |
|
|
data argument should point at an array of
|
1476 |
|
|
bytes, allowing three bytes for every entry. Byte 0 will contain the red
|
1477 |
|
|
intensity for the first entry, byte 1 green and byte 2 blue.
|
1478 |
|
|
|
1479 |
|
|
|
1480 |
|
|
For read-write palettes the palette can be updated using
|
1481 |
|
|
cyg_fb_write_palette or
|
1482 |
|
|
CYG_FB_WRITE_PALETTE. The
|
1483 |
|
|
first and count arguments
|
1484 |
|
|
are the same as for cyg_fb_read_palette, and the
|
1485 |
|
|
data argument should point at a suitable byte
|
1486 |
|
|
array packed in the same way. The when argument
|
1487 |
|
|
should be one of CYG_FB_UPDATE_NOW or
|
1488 |
|
|
CYG_FB_UPDATE_VERTICAL_RETRACE. With some displays
|
1489 |
|
|
updating the palette in the middle of an update may result in visual
|
1490 |
|
|
noise, so synchronizing to the vertical retrace avoids this. However
|
1491 |
|
|
not all device drivers will support this.
|
1492 |
|
|
|
1493 |
|
|
|
1494 |
|
|
There is an assumption that palette entries use 8 bits for each of the
|
1495 |
|
|
red, green and blue colour intensities. This is not always the case,
|
1496 |
|
|
but the device drivers will perform appropriate adjustments. Some
|
1497 |
|
|
hardware may use only 6 bits per colour, and the device driver will
|
1498 |
|
|
ignore the bottom two bits of the supplied intensity values.
|
1499 |
|
|
Occasionally hardware may use more than 8 bits, in which case the
|
1500 |
|
|
supplied 8 bits are shifted left appropriately and zero-padded. Device
|
1501 |
|
|
drivers for such hardware may also provide device-specific routines to
|
1502 |
|
|
manipulate the palette in a non-portable fashion.
|
1503 |
|
|
|
1504 |
|
|
|
1505 |
|
|
|
1506 |
|
|
|
1507 |
|
|
True Colour displays
|
1508 |
|
|
|
1509 |
|
|
True colour displays are often easier to manage than paletted
|
1510 |
|
|
displays. However this comes at the cost of extra memory. A 16bpp true
|
1511 |
|
|
colour display requires twice as much memory as an 8bpp paletted
|
1512 |
|
|
display, yet can offer only 32 or 64 levels of intensity for each
|
1513 |
|
|
colour as opposed to the 256 levels provided by a palette. It also
|
1514 |
|
|
requires twice as much video memory bandwidth to send all the pixel
|
1515 |
|
|
data to the display for every refresh, which may impact the
|
1516 |
|
|
performance of the rest of the system. A 32bpp true colour display
|
1517 |
|
|
offers the same colour intensities but requires four times the memory
|
1518 |
|
|
and four times the bandwidth.
|
1519 |
|
|
|
1520 |
|
|
|
1521 |
|
|
Exactly how the colour bits are organized in
|
1522 |
|
|
a cyg_fb_colour pixel value is not
|
1523 |
|
|
defined by the colour format. Instead code should use the
|
1524 |
|
|
cyg_fb_make_colour or
|
1525 |
|
|
CYG_FB_MAKE_COLOUR primitives. These take 8-bit
|
1526 |
|
|
intensity levels for red, green and blue, and return the corresponding
|
1527 |
|
|
cyg_fb_colour. When using the macro interface the
|
1528 |
|
|
arithmetic happens at compile-time, for example:
|
1529 |
|
|
|
1530 |
|
|
|
1531 |
|
|
#define BLACK CYG_FB_MAKE_COLOUR(FRAMEBUF, 0, 0, 0)
|
1532 |
|
|
#define WHITE CYG_FB_MAKE_COLOUR(FRAMEBUF, 255, 255, 255)
|
1533 |
|
|
#define RED CYG_FB_MAKE_COLOUR(FRAMEBUF, 255, 0, 0)
|
1534 |
|
|
#define GREEN CYG_FB_MAKE_COLOUR(FRAMEBUF, 0, 255, 0)
|
1535 |
|
|
#define BLUE CYG_FB_MAKE_COLOUR(FRAMEBUF, 0, 0, 255)
|
1536 |
|
|
#define YELLOW CYG_FB_MAKE_COLOUR(FRAMEBUF, 255, 255, 80)
|
1537 |
|
|
|
1538 |
|
|
|
1539 |
|
|
Displays vary widely so the numbers may need to be adjusted to give
|
1540 |
|
|
the exact desired colours.
|
1541 |
|
|
|
1542 |
|
|
|
1543 |
|
|
For symmetry there are also cyg_fb_break_colour
|
1544 |
|
|
and CYG_FB_BREAK_COLOUR primitives. These take a
|
1545 |
|
|
cyg_fb_colour value and decompose it into its red, green
|
1546 |
|
|
and blue components.
|
1547 |
|
|
|
1548 |
|
|
|
1549 |
|
|
|
1550 |
|
|
|
1551 |
|
|
|
1552 |
|
|
|
1553 |
|
|
|
1554 |
|
|
|
1555 |
|
|
|
1556 |
|
|
|
1557 |
|
|
Framebuffer Drawing Primitives
|
1558 |
|
|
|
1559 |
|
|
|
1560 |
|
|
Drawing Primitives
|
1561 |
|
|
updating the display
|
1562 |
|
|
|
1563 |
|
|
|
1564 |
|
|
|
1565 |
|
|
|
1566 |
|
|
#include <cyg/io/framebuf.h>
|
1567 |
|
|
|
1568 |
|
|
|
1569 |
|
|
void cyg_fb_write_pixel
|
1570 |
|
|
cyg_fb* fbdev
|
1571 |
|
|
cyg_ucount16 x
|
1572 |
|
|
cyg_ucount16 y
|
1573 |
|
|
cyg_fb_colour colour
|
1574 |
|
|
|
1575 |
|
|
|
1576 |
|
|
cyg_fb_colour cyg_fb_read_pixel
|
1577 |
|
|
cyg_fb* fbdev
|
1578 |
|
|
cyg_ucount16 x
|
1579 |
|
|
cyg_ucount16 y
|
1580 |
|
|
|
1581 |
|
|
|
1582 |
|
|
void cyg_fb_write_hline
|
1583 |
|
|
cyg_fb* fbdev
|
1584 |
|
|
cyg_ucount16 x
|
1585 |
|
|
cyg_ucount16 y
|
1586 |
|
|
cyg_ucount16 len
|
1587 |
|
|
cyg_fb_colour colour
|
1588 |
|
|
|
1589 |
|
|
|
1590 |
|
|
void cyg_fb_write_vline
|
1591 |
|
|
cyg_fb* fbdev
|
1592 |
|
|
cyg_ucount16 x
|
1593 |
|
|
cyg_ucount16 y
|
1594 |
|
|
cyg_ucount16 len
|
1595 |
|
|
cyg_fb_colour colour
|
1596 |
|
|
|
1597 |
|
|
|
1598 |
|
|
void cyg_fb_fill_block
|
1599 |
|
|
cyg_fb* fbdev
|
1600 |
|
|
cyg_ucount16 x
|
1601 |
|
|
cyg_ucount16 y
|
1602 |
|
|
cyg_ucount16 width
|
1603 |
|
|
cyg_ucount16 height
|
1604 |
|
|
cyg_fb_colour colour
|
1605 |
|
|
|
1606 |
|
|
|
1607 |
|
|
void cyg_fb_write_block
|
1608 |
|
|
cyg_fb* fbdev
|
1609 |
|
|
cyg_ucount16 x
|
1610 |
|
|
cyg_ucount16 y
|
1611 |
|
|
cyg_ucount16 width
|
1612 |
|
|
cyg_ucount16 height
|
1613 |
|
|
const void* data
|
1614 |
|
|
cyg_ucount16 offset
|
1615 |
|
|
cyg_ucount16 stride
|
1616 |
|
|
|
1617 |
|
|
|
1618 |
|
|
void cyg_fb_read_block
|
1619 |
|
|
cyg_fb* fbdev
|
1620 |
|
|
cyg_ucount16 x
|
1621 |
|
|
cyg_ucount16 y
|
1622 |
|
|
cyg_ucount16 width
|
1623 |
|
|
cyg_ucount16 height
|
1624 |
|
|
void* data
|
1625 |
|
|
cyg_ucount16 offset
|
1626 |
|
|
cyg_ucount16 stride
|
1627 |
|
|
|
1628 |
|
|
|
1629 |
|
|
void cyg_fb_move_block
|
1630 |
|
|
cyg_fb* fbdev
|
1631 |
|
|
cyg_ucount16 x
|
1632 |
|
|
cyg_ucount16 y
|
1633 |
|
|
cyg_ucount16 width
|
1634 |
|
|
cyg_ucount16 height
|
1635 |
|
|
cyg_ucount16 new_x
|
1636 |
|
|
cyg_ucount16 new_y
|
1637 |
|
|
|
1638 |
|
|
|
1639 |
|
|
void cyg_fb_synch
|
1640 |
|
|
cyg_fb* fbdev
|
1641 |
|
|
cyg_ucount16 when
|
1642 |
|
|
|
1643 |
|
|
|
1644 |
|
|
void CYG_FB_WRITE_PIXEL
|
1645 |
|
|
FRAMEBUF
|
1646 |
|
|
cyg_ucount16 x
|
1647 |
|
|
cyg_ucount16 y
|
1648 |
|
|
cyg_fb_colour colour
|
1649 |
|
|
|
1650 |
|
|
|
1651 |
|
|
cyg_fb_colour CYG_FB_READ_PIXEL
|
1652 |
|
|
FRAMEBUF
|
1653 |
|
|
cyg_ucount16 x
|
1654 |
|
|
cyg_ucount16 y
|
1655 |
|
|
|
1656 |
|
|
|
1657 |
|
|
void CYG_FB_WRITE_HLINE
|
1658 |
|
|
FRAMEBUF
|
1659 |
|
|
cyg_ucount16 x
|
1660 |
|
|
cyg_ucount16 y
|
1661 |
|
|
cyg_ucount16 len
|
1662 |
|
|
cyg_fb_colour colour
|
1663 |
|
|
|
1664 |
|
|
|
1665 |
|
|
void CYG_FB_WRITE_VLINE
|
1666 |
|
|
FRAMEBUF
|
1667 |
|
|
cyg_ucount16 x
|
1668 |
|
|
cyg_ucount16 y
|
1669 |
|
|
cyg_ucount16 len
|
1670 |
|
|
cyg_fb_colour colour
|
1671 |
|
|
|
1672 |
|
|
|
1673 |
|
|
void CYG_FB_FILL_BLOCK
|
1674 |
|
|
FRAMEBUF
|
1675 |
|
|
cyg_ucount16 x
|
1676 |
|
|
cyg_ucount16 y
|
1677 |
|
|
cyg_ucount16 width
|
1678 |
|
|
cyg_ucount16 height
|
1679 |
|
|
cyg_fb_colour colour
|
1680 |
|
|
|
1681 |
|
|
|
1682 |
|
|
void CYG_FB_WRITE_BLOCK
|
1683 |
|
|
FRAMEBUF
|
1684 |
|
|
cyg_ucount16 x
|
1685 |
|
|
cyg_ucount16 y
|
1686 |
|
|
cyg_ucount16 width
|
1687 |
|
|
cyg_ucount16 height
|
1688 |
|
|
const void* data
|
1689 |
|
|
cyg_ucount16 offset
|
1690 |
|
|
cyg_ucount16 stride
|
1691 |
|
|
|
1692 |
|
|
|
1693 |
|
|
void CYG_FB_READ_BLOCK
|
1694 |
|
|
FRAMEBUF
|
1695 |
|
|
cyg_ucount16 x
|
1696 |
|
|
cyg_ucount16 y
|
1697 |
|
|
cyg_ucount16 width
|
1698 |
|
|
cyg_ucount16 height
|
1699 |
|
|
void* data
|
1700 |
|
|
cyg_ucount16 offset
|
1701 |
|
|
cyg_ucount16 stride
|
1702 |
|
|
|
1703 |
|
|
|
1704 |
|
|
void CYG_FB_MOVE_BLOCK
|
1705 |
|
|
FRAMEBUF
|
1706 |
|
|
cyg_ucount16 x
|
1707 |
|
|
cyg_ucount16 y
|
1708 |
|
|
cyg_ucount16 width
|
1709 |
|
|
cyg_ucount16 height
|
1710 |
|
|
cyg_ucount16 new_x
|
1711 |
|
|
cyg_ucount16 new_y
|
1712 |
|
|
|
1713 |
|
|
|
1714 |
|
|
void CYG_FB_SYNCH
|
1715 |
|
|
FRAMEBUF
|
1716 |
|
|
cyg_ucount16 when
|
1717 |
|
|
|
1718 |
|
|
|
1719 |
|
|
|
1720 |
|
|
|
1721 |
|
|
|
1722 |
|
|
Description
|
1723 |
|
|
|
1724 |
|
|
The eCos framebuffer infrastructure defines a small number of drawing
|
1725 |
|
|
primitives. These are not intended to provide full graphical
|
1726 |
|
|
functionality like multiple windows, drawing text in arbitrary fonts,
|
1727 |
|
|
or anything like that. Instead they provide building blocks for
|
1728 |
|
|
higher-level graphical toolkits. The available primitives are:
|
1729 |
|
|
|
1730 |
|
|
|
1731 |
|
|
|
1732 |
|
|
Manipulating individual pixels.
|
1733 |
|
|
|
1734 |
|
|
|
1735 |
|
|
Drawing horizontal and vertical lines.
|
1736 |
|
|
|
1737 |
|
|
|
1738 |
|
|
Block fills.
|
1739 |
|
|
|
1740 |
|
|
|
1741 |
|
|
Moving blocks between the framebuffer and main memory.
|
1742 |
|
|
|
1743 |
|
|
|
1744 |
|
|
Moving blocks within the framebuffer.
|
1745 |
|
|
|
1746 |
|
|
|
1747 |
|
|
For double-buffered devices, synchronizing the framebuffer contents
|
1748 |
|
|
with the actual display.
|
1749 |
|
|
|
1750 |
|
|
|
1751 |
|
|
|
1752 |
|
|
There are two versions for each primitive: a macro and a function. The
|
1753 |
|
|
macro can be used if the desired framebuffer device is known at
|
1754 |
|
|
compile-time. Its first argument should be a framebuffer identifier,
|
1755 |
|
|
for example 320x240x16, and must be one of the
|
1756 |
|
|
entries in the configuration option
|
1757 |
|
|
CYGDAT_IO_FRAMEBUF_DEVICES. In the examples below
|
1758 |
|
|
it is assumed that FRAMEBUF has been
|
1759 |
|
|
#define'd to a suitable identifier. The function
|
1760 |
|
|
can be used if the desired framebuffer device is selected at
|
1761 |
|
|
run-time. Its first argument should be a pointer to the appropriate
|
1762 |
|
|
cyg_fb structure.
|
1763 |
|
|
|
1764 |
|
|
|
1765 |
|
|
The pixel, line, and block fill primitives take a
|
1766 |
|
|
cyg_fb_colour argument. For details of colour handling
|
1767 |
|
|
see . This argument should have no
|
1768 |
|
|
more bits set than are appropriate for the display depth. For example
|
1769 |
|
|
on a 4bpp only the bottom four bits of the colour may be set,
|
1770 |
|
|
otherwise the behaviour is undefined.
|
1771 |
|
|
|
1772 |
|
|
|
1773 |
|
|
None of the primitives will perform any run-time error checking,
|
1774 |
|
|
except possibly for some assertions in a debug build. If higher-level
|
1775 |
|
|
code provides invalid arguments, for example trying to write a block
|
1776 |
|
|
which extends past the right hand side of the screen, then the
|
1777 |
|
|
system's behaviour is undefined. It is the responsibility of
|
1778 |
|
|
higher-level code to perform clipping to the screen boundaries.
|
1779 |
|
|
|
1780 |
|
|
|
1781 |
|
|
|
1782 |
|
|
|
1783 |
|
|
Manipulating Individual Pixels
|
1784 |
|
|
|
1785 |
|
|
The primitives for manipulating individual pixels are very simple: a
|
1786 |
|
|
pixel can be written or read back. The following example shows one way
|
1787 |
|
|
of drawing a diagonal line:
|
1788 |
|
|
|
1789 |
|
|
|
1790 |
|
|
void
|
1791 |
|
|
draw_diagonal(cyg_fb* fb,
|
1792 |
|
|
cyg_ucount16 x, cyg_ucount16 y, cyg_ucount16 len,
|
1793 |
|
|
cyg_fb_colour colour)
|
1794 |
|
|
{
|
1795 |
|
|
while ( len-- ) {
|
1796 |
|
|
cyg_fb_write_pixel(fb, x++, y++, colour);
|
1797 |
|
|
}
|
1798 |
|
|
}
|
1799 |
|
|
|
1800 |
|
|
|
1801 |
|
|
The next example shows how to draw a horizontal XOR line on a 1bpp
|
1802 |
|
|
display.
|
1803 |
|
|
|
1804 |
|
|
|
1805 |
|
|
void
|
1806 |
|
|
draw_horz_xor(cyg_ucount16 x, cyg_ucount16 y, cyg_ucount16 len)
|
1807 |
|
|
{
|
1808 |
|
|
cyg_fb_colour colour;
|
1809 |
|
|
while ( len--) {
|
1810 |
|
|
colour = CYG_FB_READ_PIXEL(FRAMEBUF, x, y);
|
1811 |
|
|
CYG_FB_WRITE_PIXEL(FRAMEBUF, x++, y, colour ^ 0x01);
|
1812 |
|
|
}
|
1813 |
|
|
}
|
1814 |
|
|
|
1815 |
|
|
|
1816 |
|
|
The pixel macros should normally be avoided. Determining the correct
|
1817 |
|
|
location within framebuffer memory corresponding to a set of
|
1818 |
|
|
coordinates for each pixel is a comparatively expensive operation.
|
1819 |
|
|
Instead there is direct support for
|
1820 |
|
|
linkend="framebuf-iterating">iterating over parts of the
|
1821 |
|
|
display, avoiding unnecessary overheads.
|
1822 |
|
|
|
1823 |
|
|
|
1824 |
|
|
|
1825 |
|
|
|
1826 |
|
|
Drawing Simple Lines
|
1827 |
|
|
|
1828 |
|
|
Higher-level graphics code often needs to draw single-pixel horizontal
|
1829 |
|
|
and vertical lines. If the application involves multiple windows then
|
1830 |
|
|
these will usually have thin borders around them. Widgets such as
|
1831 |
|
|
buttons and scrollbars also often have thin borders.
|
1832 |
|
|
|
1833 |
|
|
|
1834 |
|
|
cyg_fb_draw_hline and
|
1835 |
|
|
CYG_FB_DRAW_HLINE draw a horizontal line of the
|
1836 |
|
|
specified colour, starting at the
|
1837 |
|
|
x and y coordinates and
|
1838 |
|
|
extending to the right (increasing x) for a total of
|
1839 |
|
|
len pixels. A 50 pixel line starting at
|
1840 |
|
|
(100,100) will end at (149,100).
|
1841 |
|
|
|
1842 |
|
|
|
1843 |
|
|
cyg_fb_draw_vline and
|
1844 |
|
|
CYG_FB_DRAW_VLINE take the same arguments, but
|
1845 |
|
|
the line extends down (increasing y).
|
1846 |
|
|
|
1847 |
|
|
|
1848 |
|
|
These primitives do not directly support drawing lines more than one
|
1849 |
|
|
pixel thick, but block
|
1850 |
|
|
fills can be used to achieve those. There is no generic support
|
1851 |
|
|
for drawing arbitrary lines, instead that is left to higher-level
|
1852 |
|
|
graphics toolkits.
|
1853 |
|
|
|
1854 |
|
|
|
1855 |
|
|
|
1856 |
|
|
|
1857 |
|
|
Block Fills
|
1858 |
|
|
|
1859 |
|
|
Filling a rectangular part of the screen with a solid colour is
|
1860 |
|
|
another common requirement for higher-level code. The simplest example
|
1861 |
|
|
is during initialization, to set the display's whole background to a
|
1862 |
|
|
known value. Block fills are also often used when creating new windows
|
1863 |
|
|
or drawing the bulk of a simple button or scrollbar widget.
|
1864 |
|
|
cyg_fb_fill_block and
|
1865 |
|
|
CYG_FB_FILL_BLOCK provide this functionality.
|
1866 |
|
|
|
1867 |
|
|
|
1868 |
|
|
The x and y arguments
|
1869 |
|
|
specify the top-left corner of the block to be filled. The
|
1870 |
|
|
width and height
|
1871 |
|
|
arguments specify the number of pixels affected, a total of
|
1872 |
|
|
width * height. The following example
|
1873 |
|
|
illustrates part of the process for initializing a framebuffer,
|
1874 |
|
|
assumed here to have a writeable palette with default settings.
|
1875 |
|
|
|
1876 |
|
|
|
1877 |
|
|
int
|
1878 |
|
|
display_init(void)
|
1879 |
|
|
{
|
1880 |
|
|
int result = CYG_FB_ON(FRAMEBUF);
|
1881 |
|
|
if ( result ) {
|
1882 |
|
|
return result;
|
1883 |
|
|
}
|
1884 |
|
|
CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,
|
1885 |
|
|
CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),
|
1886 |
|
|
CYG_FB_DEFAULT_PALETTE_WHITE);
|
1887 |
|
|
…
|
1888 |
|
|
}
|
1889 |
|
|
|
1890 |
|
|
|
1891 |
|
|
|
1892 |
|
|
|
1893 |
|
|
Copying Blocks between the Framebuffer and Main Memory
|
1894 |
|
|
|
1895 |
|
|
The block transfer primitives serve two main purposes: drawing images.
|
1896 |
|
|
and saving parts of the current display to be restored later. For
|
1897 |
|
|
simple linear framebuffers the primitives just implement copy
|
1898 |
|
|
operations, with no data conversion of any sort. For non-linear ones
|
1899 |
|
|
the primitives act as if the framebuffer memory was linear. For
|
1900 |
|
|
example, consider a 2bpp display where the two bits for a single pixel
|
1901 |
|
|
are split over two separate bytes in framebuffer memory, or two
|
1902 |
|
|
planes. For a block write operation the source data should still be
|
1903 |
|
|
organized with four full pixels per byte, as for a linear framebuffer
|
1904 |
|
|
of the same depth. and the block write primitive will distribute the
|
1905 |
|
|
bits over the framebuffer memory as required. Similarly a block read
|
1906 |
|
|
will combine the appropriate bits from different locations in
|
1907 |
|
|
framebuffer memory and the resulting memory block will have four full
|
1908 |
|
|
pixels per byte.
|
1909 |
|
|
|
1910 |
|
|
|
1911 |
|
|
Because the block transfer primitives perform no data conversion, if
|
1912 |
|
|
they are to be used for rendering images then those images should be
|
1913 |
|
|
pre-formatted appropriately for the framebuffer device. For small
|
1914 |
|
|
images this would normally happen on the host-side as part of the
|
1915 |
|
|
application build process. For larger images it will usually be better
|
1916 |
|
|
to store them in a compressed format and decompress them at run-time,
|
1917 |
|
|
trading off memory for cpu cycles.
|
1918 |
|
|
|
1919 |
|
|
|
1920 |
|
|
The x and y arguments
|
1921 |
|
|
specify the top-left corner of the block to be transferred, and the
|
1922 |
|
|
width and height
|
1923 |
|
|
arguments determine the size. The data,
|
1924 |
|
|
offset and stride
|
1925 |
|
|
arguments determine the location and layout of the block in main
|
1926 |
|
|
memory:
|
1927 |
|
|
|
1928 |
|
|
|
1929 |
|
|
|
1930 |
|
|
data
|
1931 |
|
|
|
1932 |
|
|
The source or destination for the transfer. For 1bpp, 2bpp and 4bpp
|
1933 |
|
|
devices the data will be packed in accordance with the framebuffer
|
1934 |
|
|
device's endianness as per the CYG_FB_FLAGS0_LE
|
1935 |
|
|
flag. Each row starts in a new byte so there may be some padding on
|
1936 |
|
|
the right. For 16bpp and 32bpp the data should be aligned to the
|
1937 |
|
|
appropriate boundary.
|
1938 |
|
|
|
1939 |
|
|
|
1940 |
|
|
|
1941 |
|
|
offset
|
1942 |
|
|
|
1943 |
|
|
Sometimes only part of an image should be written to the screen. A
|
1944 |
|
|
vertical offset can be achieved simply by adjusting
|
1945 |
|
|
data to point at the appropriate row within the
|
1946 |
|
|
image instead of the top row. For 8bpp, 16bpp and 32bpp displays
|
1947 |
|
|
an additional horizontal offset can also be achieved by adjusting
|
1948 |
|
|
data. However for 1bpp, 2bpp and 4bpp displays
|
1949 |
|
|
the starting position within the image may be in the middle of a byte.
|
1950 |
|
|
Hence the horizontal pixel offset can instead be specified with the
|
1951 |
|
|
offset argument.
|
1952 |
|
|
|
1953 |
|
|
|
1954 |
|
|
|
1955 |
|
|
stride
|
1956 |
|
|
|
1957 |
|
|
This indicates the number of bytes between rows. Usually it will be
|
1958 |
|
|
related to the width, but there are exceptions
|
1959 |
|
|
such as when drawing only part of an image.
|
1960 |
|
|
|
1961 |
|
|
|
1962 |
|
|
|
1963 |
|
|
|
1964 |
|
|
The following example fills a 4bpp display with an image held in
|
1965 |
|
|
memory and already in the right format. If the image is smaller than
|
1966 |
|
|
the display it will be centered. If the image is larger then the
|
1967 |
|
|
center portion will fill the entire display.
|
1968 |
|
|
|
1969 |
|
|
|
1970 |
|
|
void
|
1971 |
|
|
draw_image(const void* data, int width, int height)
|
1972 |
|
|
{
|
1973 |
|
|
cyg_ucount16 stride;
|
1974 |
|
|
cyg_ucount16 x, y, offset;
|
1975 |
|
|
|
1976 |
|
|
#if (4 != CYG_FB_DEPTH(FRAMEBUF))
|
1977 |
|
|
# error This code assumes a 4bpp display
|
1978 |
|
|
#endif
|
1979 |
|
|
|
1980 |
|
|
stride = (width + 1) >> 1; // 4bpp to byte stride
|
1981 |
|
|
|
1982 |
|
|
if (width < CYG_FB_WIDTH(FRAMEBUF)) {
|
1983 |
|
|
x = (CYG_FB_WIDTH(FRAMEBUF) - width) >> 1;
|
1984 |
|
|
offset = 0;
|
1985 |
|
|
} else {
|
1986 |
|
|
x = 0;
|
1987 |
|
|
offset = (width - CYG_FB_WIDTH(FRAMEBUF)) >> 1;
|
1988 |
|
|
width = CYG_FB_WIDTH(FRAMEBUF);
|
1989 |
|
|
}
|
1990 |
|
|
if (height < CYG_FB_HEIGHT(FRAMEBUF)) {
|
1991 |
|
|
y = (CYG_FB_HEIGHT(FRAMEBUF) - height) >> 1;
|
1992 |
|
|
} else {
|
1993 |
|
|
y = 0;
|
1994 |
|
|
data = (const void*)((const cyg_uint8*)data +
|
1995 |
|
|
(stride * ((height - CYG_FB_HEIGHT(FRAMEBUF)) >> 1));
|
1996 |
|
|
height = CYG_FB_HEIGHT(FRAMEBUF);
|
1997 |
|
|
}
|
1998 |
|
|
CYG_FB_WRITE_BLOCK(FRAMEBUF, x, y, width, height, data, offset, stride);
|
1999 |
|
|
}
|
2000 |
|
|
|
2001 |
|
|
|
2002 |
|
|
|
2003 |
|
|
|
2004 |
|
|
Moving Blocks with the Framebuffer
|
2005 |
|
|
|
2006 |
|
|
Sometimes it is necessary to move a block of data around the screen,
|
2007 |
|
|
especially when using a higher-level graphics toolkit that supports
|
2008 |
|
|
multiple windows. Block moves can be implemented by a read into main
|
2009 |
|
|
memory followed by a write block, but this is expensive and imposes an
|
2010 |
|
|
additional memory requirement. Instead the framebuffer infrastructure
|
2011 |
|
|
provides a generic block move primitive. It will handle all cases
|
2012 |
|
|
where the source and destination positions overlap. The
|
2013 |
|
|
x and y arguments
|
2014 |
|
|
specify the top-left corner of the block to be moved, and
|
2015 |
|
|
width and height
|
2016 |
|
|
determine the block size. new_x and
|
2017 |
|
|
new_y specify the destination. The source data
|
2018 |
|
|
will remain unchanged except in areas where it overlaps the destination.
|
2019 |
|
|
|
2020 |
|
|
|
2021 |
|
|
|
2022 |
|
|
|
2023 |
|
|
Synchronizing Double-Buffered Displays
|
2024 |
|
|
|
2025 |
|
|
Some framebuffer devices are double-buffered: the framebuffer memory
|
2026 |
|
|
that gets manipulated by the drawing primitives is separate from what
|
2027 |
|
|
is actually displayed, and a synch operation is needed to update the
|
2028 |
|
|
display. In some cases this may be because the actual display memory
|
2029 |
|
|
is not directly accessible by the processor, for example it may
|
2030 |
|
|
instead be attached via an SPI bus. Instead drawing happens in a
|
2031 |
|
|
buffer in main memory, and then this gets transferred over the SPI bus
|
2032 |
|
|
to the actual display hardware during a synch. In other cases it may
|
2033 |
|
|
be a software artefact. Some drawing operations, especially ones
|
2034 |
|
|
involving complex curves, can take a very long time and it may be
|
2035 |
|
|
considered undesirable to have the user see this happening a few
|
2036 |
|
|
pixels at a time. Instead the drawing happens in a separate buffer in
|
2037 |
|
|
main memory and then a double buffer synch just involves a block move
|
2038 |
|
|
to framebuffer memory. Typically that block move is much faster than
|
2039 |
|
|
the drawing operation. Obviously there is a cost: an extra area of
|
2040 |
|
|
memory, and the synch operation itself can consume many cycles and
|
2041 |
|
|
much of the available memory bandwidth.
|
2042 |
|
|
|
2043 |
|
|
|
2044 |
|
|
It is the responsibility of the framebuffer device driver to provide
|
2045 |
|
|
the extra main memory. As far as higher-level code is concerned the
|
2046 |
|
|
only difference between an ordinary and a double-buffered display is
|
2047 |
|
|
that with the latter changes do not become visible until a synch
|
2048 |
|
|
operation has been performed. The framebuffer infrastructure provides
|
2049 |
|
|
support for a bounding box, keeping track of what has been updated
|
2050 |
|
|
since the last synch. This means only the updated part of the screen
|
2051 |
|
|
has to be transferred to the display hardware.
|
2052 |
|
|
|
2053 |
|
|
|
2054 |
|
|
The synch primitives take two arguments. The first identifies the
|
2055 |
|
|
framebuffer device. The second should be one of
|
2056 |
|
|
CYG_FB_UPDATE_NOW for an immediate update, or
|
2057 |
|
|
CYG_FB_UPDATE_VERTICAL_RETRACE. Some display
|
2058 |
|
|
hardware involves a lengthy vertical retrace period every 10-20
|
2059 |
|
|
milliseconds during which nothing gets drawn to the screen, and
|
2060 |
|
|
performing the synch during this time means that the end user is
|
2061 |
|
|
unaware of the operation (assuming the synch can be completed in the
|
2062 |
|
|
time available). When the hardware supports it, specifying
|
2063 |
|
|
CYG_FB_UPDATE_VERTICAL_RETRACE means that the synch
|
2064 |
|
|
operation will block until the next vertical retrace takes place and
|
2065 |
|
|
then perform the update. This may be an expensive operation, for
|
2066 |
|
|
example it may involve polling a bit in a register. In a
|
2067 |
|
|
multi-threaded environment it may also be unreliable because the
|
2068 |
|
|
thread performing the synch may get interrupted or rescheduled in the
|
2069 |
|
|
middle of the operation. When the hardware does not involve vertical
|
2070 |
|
|
retraces, or when there is no easy way to detect them, the second
|
2071 |
|
|
argument to the synch operation will just be ignored and the update
|
2072 |
|
|
will always happen immediately.
|
2073 |
|
|
|
2074 |
|
|
|
2075 |
|
|
It is up to higher level code to determine when a synch operation is
|
2076 |
|
|
appropriate. One approach for typical event-driven code is to perform
|
2077 |
|
|
the synch at the start of the event loop, just before waiting for an
|
2078 |
|
|
input or timer event. This may not be optimal. For example if there
|
2079 |
|
|
two small updates to opposite corners of the screen then it would be
|
2080 |
|
|
better to make two synch calls with small bounding boxes, rather than
|
2081 |
|
|
a single synch call with a a large bounding box that requires most of
|
2082 |
|
|
the framebuffer memory to be updated.
|
2083 |
|
|
|
2084 |
|
|
|
2085 |
|
|
Leaving out the synch operations leads to portability problems. On
|
2086 |
|
|
hardware which does not involve double-buffering the synch operation
|
2087 |
|
|
is a no-op, usually eliminated at compile-time, so invoking synch does
|
2088 |
|
|
not add any code size or cpu cycle overhead. On double-buffered
|
2089 |
|
|
hardware, leaving out the synch means the user cannot see what has
|
2090 |
|
|
been drawn into the framebuffer.
|
2091 |
|
|
|
2092 |
|
|
|
2093 |
|
|
|
2094 |
|
|
|
2095 |
|
|
|
2096 |
|
|
|
2097 |
|
|
|
2098 |
|
|
|
2099 |
|
|
|
2100 |
|
|
|
2101 |
|
|
Framebuffer Pixel Manipulation
|
2102 |
|
|
|
2103 |
|
|
|
2104 |
|
|
Pixel Manipulation
|
2105 |
|
|
iterating over the display
|
2106 |
|
|
|
2107 |
|
|
|
2108 |
|
|
|
2109 |
|
|
|
2110 |
|
|
#include <cyg/io/framebuf.h>
|
2111 |
|
|
|
2112 |
|
|
|
2113 |
|
|
CYG_FB_PIXEL0_VAR
|
2114 |
|
|
FRAMEBUF
|
2115 |
|
|
|
2116 |
|
|
|
2117 |
|
|
void CYG_FB_PIXEL0_SET
|
2118 |
|
|
FRAMEBUF
|
2119 |
|
|
cyg_ucount16 x
|
2120 |
|
|
cyg_ucount16 y
|
2121 |
|
|
|
2122 |
|
|
|
2123 |
|
|
void CYG_FB_PIXEL0_GET
|
2124 |
|
|
FRAMEBUF
|
2125 |
|
|
cyg_ucount16 x
|
2126 |
|
|
cyg_ucount16 y
|
2127 |
|
|
|
2128 |
|
|
|
2129 |
|
|
void CYG_FB_PIXEL0_ADDX
|
2130 |
|
|
FRAMEBUF
|
2131 |
|
|
cyg_ucount16 incr
|
2132 |
|
|
|
2133 |
|
|
|
2134 |
|
|
void CYG_FB_PIXEL0_ADDY
|
2135 |
|
|
FRAMEBUF
|
2136 |
|
|
cyg_ucount16 incr
|
2137 |
|
|
|
2138 |
|
|
|
2139 |
|
|
void CYG_FB_PIXEL0_WRITE
|
2140 |
|
|
FRAMEBUF
|
2141 |
|
|
cyg_fb_colour colour
|
2142 |
|
|
|
2143 |
|
|
|
2144 |
|
|
cyg_fb_colour CYG_FB_PIXEL0_READ
|
2145 |
|
|
FRAMEBUF
|
2146 |
|
|
|
2147 |
|
|
|
2148 |
|
|
void CYG_FB_PIXEL0_FLUSHABS
|
2149 |
|
|
FRAMEBUF
|
2150 |
|
|
cyg_ucount16 x0
|
2151 |
|
|
cyg_ucount16 y0
|
2152 |
|
|
cyg_ucount16 width
|
2153 |
|
|
cyg_ucount16 height
|
2154 |
|
|
|
2155 |
|
|
|
2156 |
|
|
void CYG_FB_PIXEL0_FLUSHREL
|
2157 |
|
|
FRAMEBUF
|
2158 |
|
|
cyg_ucount16 x0
|
2159 |
|
|
cyg_ucount16 y0
|
2160 |
|
|
cyg_ucount16 dx
|
2161 |
|
|
cyg_ucount16 dy
|
2162 |
|
|
|
2163 |
|
|
|
2164 |
|
|
|
2165 |
|
|
|
2166 |
|
|
|
2167 |
|
|
Description
|
2168 |
|
|
|
2169 |
|
|
A common requirement for graphics code is to iterate over parts of the
|
2170 |
|
|
framebuffer. Drawing text typically involves iterating over a block
|
2171 |
|
|
of pixels for each character, say 8 by 8, setting each pixel to either
|
2172 |
|
|
a foreground or background colour. Drawing arbitrary lines typically
|
2173 |
|
|
involves moving to the start position and then adjusting the x and y
|
2174 |
|
|
coordinates until the end position is reached, setting a single pixel
|
2175 |
|
|
each time around the loop. Drawing images which are not in the frame
|
2176 |
|
|
buffer's native format typically involves iterating over a block of
|
2177 |
|
|
pixels, from top to bottom and left to right, setting pixels as the
|
2178 |
|
|
image is decoded.
|
2179 |
|
|
|
2180 |
|
|
|
2181 |
|
|
Functionality like this can be implemented in several ways. One
|
2182 |
|
|
approach is to use the pixel write primitive. Typically this involves
|
2183 |
|
|
some arithmetic to get from the x and y coordinates to a location
|
2184 |
|
|
within framebuffer memory so it is fairly expensive compared with a
|
2185 |
|
|
loop which just increments a pointer. Another approach is to write the
|
2186 |
|
|
data first to a separate buffer in memory and then use a block write
|
2187 |
|
|
primitive to move it to the framebuffer, but again this involves
|
2188 |
|
|
overhead. The eCos framebuffer support provides a third approach: a
|
2189 |
|
|
set of macros specifically for iterating over the frame buffer.
|
2190 |
|
|
Depending on the operation being performed and the details of the
|
2191 |
|
|
framebuffer implementation, these macros may be optimal or
|
2192 |
|
|
near-optimal. Obviously there are limitations. Most importantly the
|
2193 |
|
|
framebuffer device must be known at compile-time: the compiler can do
|
2194 |
|
|
a better job optimizing the code if information such as the frame
|
2195 |
|
|
buffer width are constant. Also each iteration must be performed
|
2196 |
|
|
within a single variable scope: it is not possible to do some of the
|
2197 |
|
|
iteration in one function, some in another.
|
2198 |
|
|
|
2199 |
|
|
|
2200 |
|
|
|
2201 |
|
|
|
2202 |
|
|
The Pixel Macros
|
2203 |
|
|
|
2204 |
|
|
All the pixel macros take a framebuffer identifier as their first
|
2205 |
|
|
argument. This is the same identifier that can be used with the other
|
2206 |
|
|
macros like CYG_FB_WRITE_HLINE and
|
2207 |
|
|
CYG_FB_ON, one of the entries in the
|
2208 |
|
|
configuration option CYGDAT_IO_FRAMEBUF_DEVICES.
|
2209 |
|
|
Using an invalid identifier will result in numerous compile-time error
|
2210 |
|
|
messages which may bear little resemblance to the original code. In
|
2211 |
|
|
the examples below it is assumed that FRAMEBUF has
|
2212 |
|
|
been #define'd to a suitable identifier.
|
2213 |
|
|
|
2214 |
|
|
|
2215 |
|
|
Typical use of the pixel macros will look like this:
|
2216 |
|
|
|
2217 |
|
|
|
2218 |
|
|
CYG_FB_PIXEL0_VAR(FRAMEBUF);
|
2219 |
|
|
…
|
2220 |
|
|
CYG_FB_PIXEL0_FLUSHABS(FRAMEBUF, x, y, width, height);
|
2221 |
|
|
|
2222 |
|
|
|
2223 |
|
|
The VAR macro will define one or more local
|
2224 |
|
|
variables to keep track of the current pixel position, as appropriate
|
2225 |
|
|
to the framebuffer device. The other pixel macros will then use these
|
2226 |
|
|
variables. For a simple 8bpp linear framebuffer there will be just a
|
2227 |
|
|
byte pointer. For a 1bpp display there may be several variables: a
|
2228 |
|
|
byte pointer, a bit index within that byte, and possibly a cached
|
2229 |
|
|
byte; using a cached value means that the framebuffer may only get
|
2230 |
|
|
read and written once for every 8 pixels, and the compiler may well
|
2231 |
|
|
allocate a register for the cached value; on some platforms
|
2232 |
|
|
framebuffer access will bypass the processor's main cache, so reading
|
2233 |
|
|
from or writing to framebuffer memory will be slow; reducing the
|
2234 |
|
|
number of framebuffer accesses may greatly improve performance.
|
2235 |
|
|
|
2236 |
|
|
|
2237 |
|
|
Because the VAR macro defines one or more local
|
2238 |
|
|
variables it is normally placed at the start of a function or block,
|
2239 |
|
|
alongside other local variable definitions.
|
2240 |
|
|
|
2241 |
|
|
|
2242 |
|
|
One the iteration has been completed there should be a
|
2243 |
|
|
FLUSHABS or FLUSHREL macro.
|
2244 |
|
|
This serves two purposes. First, if the local variables involve a
|
2245 |
|
|
dirty cached value or similar state then this will be written back.
|
2246 |
|
|
Second, for double-buffered displays the macro sets a bounding box for
|
2247 |
|
|
the part of the screen that has been updated. This allows the double
|
2248 |
|
|
buffer synch operation to update only the part of the display that has
|
2249 |
|
|
been modified, without having to keep track of the current bounding
|
2250 |
|
|
box for every updated pixel. For FLUSHABS the
|
2251 |
|
|
x0 and y0 arguments
|
2252 |
|
|
specify the top-left corner of the bounding box, which extends for
|
2253 |
|
|
width by height pixels.
|
2254 |
|
|
For FLUSHREL x0 and
|
2255 |
|
|
y0 still specify the top-left corner, but the
|
2256 |
|
|
bottom-right corner is now determined from the current pixel position
|
2257 |
|
|
offset by dx and dy.
|
2258 |
|
|
More specifically, dx should move the current
|
2259 |
|
|
horizontal position one pixel to the right of the right-most pixel
|
2260 |
|
|
modified, such that
|
2261 |
|
|
(x + dx) - x0 gives the width
|
2262 |
|
|
of the bounding box. Similarly dy should move
|
2263 |
|
|
the current vertical position one pixel below the bottom-most pixel
|
2264 |
|
|
modified. In typical code the current pixel position will already
|
2265 |
|
|
correspond in part or in whole to the bounding box corner, as a
|
2266 |
|
|
consequence of iterating over the block of memory.
|
2267 |
|
|
|
2268 |
|
|
|
2269 |
|
|
If a pixel variable has been used only for reading framebuffer memory,
|
2270 |
|
|
not for modifying it, then it should still be flushed. A
|
2271 |
|
|
FLUSHABS with a width and height of 0 can be used
|
2272 |
|
|
to indicate that the bounding box is empty. If it is known that the
|
2273 |
|
|
framebuffer device being used does not support double-buffering then
|
2274 |
|
|
again it is possible to specify an empty bounding box. Otherwise
|
2275 |
|
|
portable code should specify a correct bounding box. If the
|
2276 |
|
|
framebuffer device that ends up being used does not support double
|
2277 |
|
|
buffering then the relevant macro arguments are eliminated at
|
2278 |
|
|
compile-time and do not result in any unnecessary code. In addition if
|
2279 |
|
|
there is no cached value or other state then the whole flush operation
|
2280 |
|
|
will be a no-op and no code will be generated.
|
2281 |
|
|
|
2282 |
|
|
|
2283 |
|
|
Failure to perform the flush may result in strange drawing artefacts
|
2284 |
|
|
on some displays which can be very hard to debug. A
|
2285 |
|
|
FLUSHABS or FLUSHREL macro
|
2286 |
|
|
only needs to be invoked once, at the end of the iteration.
|
2287 |
|
|
|
2288 |
|
|
|
2289 |
|
|
The SET macro sets the current position within the
|
2290 |
|
|
framebuffer. It can be used many times within an iteration. However
|
2291 |
|
|
it tends to be somewhat more expensive than ADDX or
|
2292 |
|
|
ADDY, so usually SET is only
|
2293 |
|
|
executed once at the start of an iteration.
|
2294 |
|
|
|
2295 |
|
|
|
2296 |
|
|
CYG_FB_PIXEL0_VAR(FRAMEBUF);
|
2297 |
|
|
CYG_FB_PIXEL0_SET(FRAMEBUF, x, y);
|
2298 |
|
|
…
|
2299 |
|
|
CYG_FB_PIXEL0_FLUSHREL(FRAMEBUF, x, y, 0, 0);
|
2300 |
|
|
|
2301 |
|
|
|
2302 |
|
|
The GET macro retrieves the x and y coordinates
|
2303 |
|
|
corresponding to the current position. It is provided mainly for
|
2304 |
|
|
symmetry, but can prove useful for debugging.
|
2305 |
|
|
|
2306 |
|
|
|
2307 |
|
|
CYG_FB_PIXEL0_VAR(FRAMEBUF);
|
2308 |
|
|
CYG_FB_PIXEL0_SET(FRAMEBUF, x, y);
|
2309 |
|
|
…
|
2310 |
|
|
#ifdef DEBUG
|
2311 |
|
|
CYG_FB_PIXEL0_GET(FRAMEBUF, new_x, new_y);
|
2312 |
|
|
diag_printf("Halfway through: x now %d, y now %d\n", new_x, new_y);
|
2313 |
|
|
#endif
|
2314 |
|
|
…
|
2315 |
|
|
CYG_FB_PIXEL0_FLUSHREL(FRAMEBUF, x, y, 0, 0);
|
2316 |
|
|
|
2317 |
|
|
|
2318 |
|
|
The ADDX and ADDY macros adjust
|
2319 |
|
|
the current position. The most common increments are 1 and -1, moving
|
2320 |
|
|
to the next or previous pixel horizontally or vertically, but any
|
2321 |
|
|
increment can be used.
|
2322 |
|
|
|
2323 |
|
|
|
2324 |
|
|
CYG_FB_PIXEL0_VAR(FRAMEBUF);
|
2325 |
|
|
CYG_FB_PIXEL0_SET(FRAMEBUF, x, y);
|
2326 |
|
|
for (rows = height; rows; rows--) {
|
2327 |
|
|
for (columns = width; columns; columns--) {
|
2328 |
|
|
<perform operation>
|
2329 |
|
|
CYG_FB_PIXEL0_ADDX(FRAMEBUF, 1);
|
2330 |
|
|
}
|
2331 |
|
|
CYG_FB_PIXEL0_ADDX(FRAMEBUF, -1 * width);
|
2332 |
|
|
CYG_FB_PIXEL0_ADDY(FRAMEBUF, 1);
|
2333 |
|
|
}
|
2334 |
|
|
CYG_FB_PIXEL0_FLUSHREL(FRAMEBUF, x, y, width, 0);
|
2335 |
|
|
|
2336 |
|
|
|
2337 |
|
|
Here the current position is moved one pixel to the right each time
|
2338 |
|
|
around the inner loop. In the outer loop the position is first moved
|
2339 |
|
|
back to the start of the current row, then moved one pixel down.
|
2340 |
|
|
For the final flush the current x position is off by
|
2341 |
|
|
width, but the current y position is already correct.
|
2342 |
|
|
|
2343 |
|
|
|
2344 |
|
|
The final two macros READ and
|
2345 |
|
|
WRITE can be used to examine or update the current
|
2346 |
|
|
pixel value.
|
2347 |
|
|
|
2348 |
|
|
|
2349 |
|
|
CYG_FB_PIXEL0_VAR(FRAMEBUF);
|
2350 |
|
|
CYG_FB_PIXEL0_SET(FRAMEBUF, x, y);
|
2351 |
|
|
for (rows = height; rows; rows--) {
|
2352 |
|
|
for (columns = width; columns; columns--) {
|
2353 |
|
|
cyg_fb_colour colour = CYG_FB_PIXEL0_READ(FRAMEBUF);
|
2354 |
|
|
if (colour == colour_to_replace) {
|
2355 |
|
|
CYG_FB_PIXEL0_WRITE(FRAMEBUF, replacement);
|
2356 |
|
|
}
|
2357 |
|
|
CYG_FB_PIXEL0_ADDX(FRAMEBUF, 1);
|
2358 |
|
|
}
|
2359 |
|
|
CYG_FB_PIXEL0_ADDX(FRAMEBUF, -1 * width);
|
2360 |
|
|
CYG_FB_PIXEL0_ADDY(FRAMEBUF, 1);
|
2361 |
|
|
}
|
2362 |
|
|
CYG_FB_PIXEL0_FLUSHREL(FRAMEBUF, x, y, width, 0);
|
2363 |
|
|
|
2364 |
|
|
|
2365 |
|
|
|
2366 |
|
|
|
2367 |
|
|
Concurrent Iterations
|
2368 |
|
|
|
2369 |
|
|
Although uncommon, in some cases application code may need to iterate
|
2370 |
|
|
over two or more blocks. An example might be an advanced block move
|
2371 |
|
|
where each copied pixel requires some processing. To support this
|
2372 |
|
|
there are PIXEL1, PIXEL2 and
|
2373 |
|
|
PIXEL3 variants of all the
|
2374 |
|
|
PIXEL0 macros. For example:
|
2375 |
|
|
|
2376 |
|
|
|
2377 |
|
|
CYG_FB_PIXEL0_VAR(FRAMEBUF);
|
2378 |
|
|
CYG_FB_PIXEL1_VAR(FRAMEBUF);
|
2379 |
|
|
|
2380 |
|
|
CYG_FB_PIXEL0_SET(FRAMEBUF, dest_x, dest_y_);
|
2381 |
|
|
CYG_FB_PIXEL1_SET(FRAMEBUF, source_x, source_y);
|
2382 |
|
|
for (rows = height; rows; rows--) {
|
2383 |
|
|
for (columns = width; columns; columns--) {
|
2384 |
|
|
colour = CYG_FB_PIXEL1_READ(FRAMEBUF);
|
2385 |
|
|
<do some processing on colour>
|
2386 |
|
|
CYG_FB_PIXEL0_WRITE(FRAMEBUF, colour);
|
2387 |
|
|
CYG_FB_PIXEL0_ADDX(FRAMEBUF, 1);
|
2388 |
|
|
CYG_FB_PIXEL1_ADDX(FRAMEBUF, 1);
|
2389 |
|
|
}
|
2390 |
|
|
CYG_FB_PIXEL0_ADDX(FRAMEBUF, -100);
|
2391 |
|
|
CYG_FB_PIXEL0_ADDY(FRAMEBUF, 1);
|
2392 |
|
|
CYG_FB_PIXEL1_ADDX(FRAMEBUF, -100);
|
2393 |
|
|
CYG_FB_PIXEL1_ADDY(FRAMEBUF, 1);
|
2394 |
|
|
}
|
2395 |
|
|
|
2396 |
|
|
CYG_FB_PIXEL0_FLUSHABS(FRAMEBUF, source_x, source_y, width, height);
|
2397 |
|
|
CYG_FB_PIXEL1_FLUSHABS(FRAMEBUF, 0, 0, 0, 0); // Only used for reading
|
2398 |
|
|
|
2399 |
|
|
|
2400 |
|
|
The PIXEL0, PIXEL1,
|
2401 |
|
|
PIXEL2 and PIXEL3 macros all use
|
2402 |
|
|
different local variables so there are no conflicts. The variable
|
2403 |
|
|
names also depend on the framebuffer device. If the target has two
|
2404 |
|
|
displays and two active framebuffer devices then the pixel macros can
|
2405 |
|
|
be used with the two devices without conflict:
|
2406 |
|
|
|
2407 |
|
|
|
2408 |
|
|
CYG_FB_PIXEL0_VAR(FRAMEBUF0);
|
2409 |
|
|
CYG_FB_PIXEL0_VAR(FRAMEBUF1);
|
2410 |
|
|
…
|
2411 |
|
|
|
2412 |
|
|
|
2413 |
|
|
|
2414 |
|
|
|
2415 |
|
|
|
2416 |
|
|
|
2417 |
|
|
|
2418 |
|
|
|
2419 |
|
|
|
2420 |
|
|
|
2421 |
|
|
Writing a Framebuffer Device Driver
|
2422 |
|
|
|
2423 |
|
|
|
2424 |
|
|
Porting
|
2425 |
|
|
writing a new framebuffer device driver
|
2426 |
|
|
|
2427 |
|
|
|
2428 |
|
|
|
2429 |
|
|
Description
|
2430 |
|
|
|
2431 |
|
|
As with most device drivers, the easiest way to write a new
|
2432 |
|
|
framebuffer package is to start with an existing one. Suitable ones
|
2433 |
|
|
include the PC VGA mode13 driver, an 8bpp paletted display, and the
|
2434 |
|
|
ARM iPAQ driver, a 16bpp true colour display. This document only
|
2435 |
|
|
outlines the process.
|
2436 |
|
|
|
2437 |
|
|
|
2438 |
|
|
Before writing any code it is necessary to decide how many framebuffer
|
2439 |
|
|
devices should be provided by the device driver. Each such device
|
2440 |
|
|
requires a cyg_fb structure and appropriate
|
2441 |
|
|
functions, and an identifier for use with the macro API plus
|
2442 |
|
|
associated macros. There are no hard rules here. Some device drivers
|
2443 |
|
|
may support just a single device, others may support many devices
|
2444 |
|
|
which drive the hardware in different modes or orientations. Optional
|
2445 |
|
|
functionality such as viewports and page flipping may be supported by
|
2446 |
|
|
having different cyg_fb devices, or by a
|
2447 |
|
|
number of configuration options which affect a single
|
2448 |
|
|
cyg_fb device. Usually providing multiple
|
2449 |
|
|
cyg_fb structures is harmless because the
|
2450 |
|
|
unused ones will get eliminated at link-time.
|
2451 |
|
|
|
2452 |
|
|
|
2453 |
|
|
|
2454 |
|
|
|
2455 |
|
|
Configuration
|
2456 |
|
|
|
2457 |
|
|
The CDL for a framebuffer package is usually straightforward. A
|
2458 |
|
|
framebuffer package should be a hardware package and reside in the
|
2459 |
|
|
devs/framebuf hierarchy,
|
2460 |
|
|
further organized by architecture. Generic framebuffer packages, if
|
2461 |
|
|
any, can go into a generic
|
2462 |
|
|
subdirectory, and will normally rely on the platform HAL to provide
|
2463 |
|
|
some platform-specific information such as base addresses. The package
|
2464 |
|
|
should be part of the target definition and hence loaded
|
2465 |
|
|
automatically, but should be
|
2466 |
|
|
active_if CYGPKG_IO_FRAMEBUF so that the
|
2467 |
|
|
driver only gets built if the generic framebuffer support is
|
2468 |
|
|
explicitly added to the configuration.
|
2469 |
|
|
|
2470 |
|
|
|
2471 |
|
|
The configuration option CYGDAT_IO_FRAMEBUF_DEVICES
|
2472 |
|
|
should hold all the valid identifiers which can be used as the first
|
2473 |
|
|
argument for the macro API. This helps application developers to
|
2474 |
|
|
select the appropriate identifier, and allows higher-level graphics
|
2475 |
|
|
library packages to check that they have been configured correctly.
|
2476 |
|
|
This is achieved using something like the following, where
|
2477 |
|
|
mode13_320x200x8 is a valid identifier for the PC
|
2478 |
|
|
VGA driver:
|
2479 |
|
|
|
2480 |
|
|
|
2481 |
|
|
requires { is_substr(CYGDAT_IO_FRAMEBUF_DEVICES, " mode13_320x200x8 ") }
|
2482 |
|
|
|
2483 |
|
|
|
2484 |
|
|
The spaces ensure that the CDL inference engine keeps the identifiers
|
2485 |
|
|
separate.
|
2486 |
|
|
|
2487 |
|
|
|
2488 |
|
|
CYGPKG_IO_FRAMEBUF contains a number of interfaces
|
2489 |
|
|
which should be implemented by individual device drivers when
|
2490 |
|
|
appropriate. This is used to eliminate some code or data structure
|
2491 |
|
|
fields at compile-time, keeping down memory requirements. The
|
2492 |
|
|
interfaces are
|
2493 |
|
|
CYGHWR_IO_FRAMEBUF_FUNCTIONALITY_32BPP,
|
2494 |
|
|
CYGHWR_IO_FRAMEBUF_FUNCTIONALITY_TRUE_COLOUR,
|
2495 |
|
|
CYGHWR_IO_FRAMEBUF_FUNCTIONALITY_PALETTE,
|
2496 |
|
|
CYGHWR_IO_FRAMEBUF_FUNCTIONALITY_WRITEABLE_PALETTE,
|
2497 |
|
|
CYGHWR_IO_FRAMEBUF_FUNCTIONALITY_DOUBLE_BUFFER,
|
2498 |
|
|
and CYGHWR_IO_FRAMEBUF_FUNCTIONALITY_VIEWPORT.
|
2499 |
|
|
For example if a device driver provides a true colour display but
|
2500 |
|
|
fails to implement the relevant interface then functions like
|
2501 |
|
|
cyg_fb_make_colour will be no-ops.
|
2502 |
|
|
|
2503 |
|
|
|
2504 |
|
|
Device drivers for paletted displays should observe the generic
|
2505 |
|
|
configuration option
|
2506 |
|
|
CYGFUN_IO_FRAMEBUF_INSTALL_DEFAULT_PALETTE and
|
2507 |
|
|
install either cyg_fb_palette_ega or
|
2508 |
|
|
cyg_fb_palette_vga as part of their
|
2509 |
|
|
cyg_fb_on implementation.
|
2510 |
|
|
|
2511 |
|
|
|
2512 |
|
|
|
2513 |
|
|
|
2514 |
|
|
Exported Header File(s)
|
2515 |
|
|
|
2516 |
|
|
Each framebuffer device driver should export one or more header files
|
2517 |
|
|
to cyg/io/framebufs. A custom
|
2518 |
|
|
build step in CYGPKG_IO_FRAMEBUF ensures that
|
2519 |
|
|
application code can just #include
|
2520 |
|
|
class="headerfile">cyg/io/framebuf.h and this will
|
2521 |
|
|
automatically include the device-specific headers. Drivers may export
|
2522 |
|
|
one header per cyg_fb device or a single
|
2523 |
|
|
header for all devices, without affecting any code outside the device
|
2524 |
|
|
driver.
|
2525 |
|
|
|
2526 |
|
|
|
2527 |
|
|
Each exported header serves two purposes. First it defines the
|
2528 |
|
|
parameters,
|
2529 |
|
|
linkend="framebuf-drawing">drawing primitive macros, and
|
2530 |
|
|
iteration macros for each
|
2531 |
|
|
device. Second it declares the cyg_fb
|
2532 |
|
|
structure.
|
2533 |
|
|
|
2534 |
|
|
|
2535 |
|
|
Parameters
|
2536 |
|
|
|
2537 |
|
|
The parameter section should resemble the following:
|
2538 |
|
|
|
2539 |
|
|
|
2540 |
|
|
#define CYG_FB_320x240x16_STRUCT cyg_ipaq_fb_320x240x16
|
2541 |
|
|
#define CYG_FB_320x240x16_DEPTH 16
|
2542 |
|
|
#define CYG_FB_320x240x16_FORMAT CYG_FB_FORMAT_16BPP_TRUE_565
|
2543 |
|
|
#define CYG_FB_320x240x16_WIDTH 320
|
2544 |
|
|
#define CYG_FB_320x240x16_HEIGHT 240
|
2545 |
|
|
#define CYG_FB_320x240x16_VIEWPORT_WIDTH 320
|
2546 |
|
|
#define CYG_FB_320x240x16_VIEWPORT_HEIGHT 240
|
2547 |
|
|
#define CYG_FB_320x240x16_FLAGS0 (CYG_FB_FLAGS0_LINEAR_FRAMEBUFFER | \
|
2548 |
|
|
CYG_FB_FLAGS0_TRUE_COLOUR | \
|
2549 |
|
|
CYG_FB_FLAGS0_BLANK | \
|
2550 |
|
|
CYG_FB_FLAGS0_BACKLIGHT)
|
2551 |
|
|
#define CYG_FB_320x240x16_FLAGS1 0
|
2552 |
|
|
#define CYG_FB_320x240x16_FLAGS2 0
|
2553 |
|
|
#define CYG_FB_320x240x16_FLAGS3 0
|
2554 |
|
|
#define CYG_FB_320x240x16_BASE ((void*)0x01FC0020)
|
2555 |
|
|
#define CYG_FB_320x240x16_STRIDE 640
|
2556 |
|
|
|
2557 |
|
|
|
2558 |
|
|
Here 320x240x16 is the framebuffer identifier for
|
2559 |
|
|
use with the macro API. Application code like:
|
2560 |
|
|
|
2561 |
|
|
|
2562 |
|
|
#define FRAMEBUF 320x240x16
|
2563 |
|
|
cyg_ucount16 width = CYG_FB_WIDTH(FRAMEBUF);
|
2564 |
|
|
|
2565 |
|
|
|
2566 |
|
|
will end up using the CYG_FB_320x240x16_WIDTH
|
2567 |
|
|
definition. To allow for efficient portable code all parameters must
|
2568 |
|
|
be compile-time constants. If the hardware may allow some of the
|
2569 |
|
|
parameters to be varied, for example different resolutions, then this
|
2570 |
|
|
should be handled either by defining separate devices for each
|
2571 |
|
|
resolution or by configuration options.
|
2572 |
|
|
|
2573 |
|
|
|
2574 |
|
|
The viewport width and height should always be defined. If the device
|
2575 |
|
|
driver does not support a viewport then these will be the same as the
|
2576 |
|
|
standard width and height.
|
2577 |
|
|
|
2578 |
|
|
|
2579 |
|
|
To allow for future expansion there are FLAGS1,
|
2580 |
|
|
FLAGS2 and FLAGS3 parameters. No
|
2581 |
|
|
flags are defined for these at present, but device drivers should
|
2582 |
|
|
still define the parameters.
|
2583 |
|
|
|
2584 |
|
|
|
2585 |
|
|
|
2586 |
|
|
|
2587 |
|
|
Drawing Primitives
|
2588 |
|
|
|
2589 |
|
|
For each device the exported header file should define macros for the
|
2590 |
|
|
drawing primitives, using the same naming convention as for
|
2591 |
|
|
parameters. In the case of true colour displays there should also be
|
2592 |
|
|
macros for the make-colour and break-colour primitives:
|
2593 |
|
|
|
2594 |
|
|
|
2595 |
|
|
#define CYG_FB_320x240x16_WRITE_PIXEL(_x_, _y_, _colour_) …
|
2596 |
|
|
#define CYG_FB_320x240x16_READ_PIXEL(_x_, _y_) …
|
2597 |
|
|
#define CYG_FB_320x240x16_WRITE_HLINE(_x_, _y_, _len_, _colour_) …
|
2598 |
|
|
#define CYG_FB_320x240x16_WRITE_VLINE(_x_, _y_, _len_, _colour_) …
|
2599 |
|
|
#define CYG_FB_320x240x16_FILL_BLOCK(_x_, _y_, _w_, _h_, _colour_) …
|
2600 |
|
|
#define CYG_FB_320x240x16_WRITE_BLOCK(_x_, _y_, _w_, _h_, _data_, _off_, _s_) …
|
2601 |
|
|
#define CYG_FB_320x240x16_READ_BLOCK(_x_, _y_, _w_, _h_, _data_, _off_, _s_) …
|
2602 |
|
|
#define CYG_FB_320x240x16_MOVE_BLOCK(_x_, _y_, _w_, _h_, _new_x_, _new_y_) …
|
2603 |
|
|
#define CYG_FB_320x240x16_MAKE_COLOUR(_r_, _g_, _b_) …
|
2604 |
|
|
#define CYG_FB_320x240x16_BREAK_COLOUR(_colour_, _r_, _g_, _b_) …
|
2605 |
|
|
|
2606 |
|
|
|
2607 |
|
|
For typical linear framebuffers there are default implementations of
|
2608 |
|
|
all of these primitives in the generic framebuffer package, held in
|
2609 |
|
|
the exported header
|
2610 |
|
|
class="headerfile">cyg/io/framebuf.inl. Hence the
|
2611 |
|
|
definitions will typically look something like:
|
2612 |
|
|
|
2613 |
|
|
|
2614 |
|
|
#include <cyg/io/framebuf.inl>
|
2615 |
|
|
…
|
2616 |
|
|
#define CYG_FB_320x240x16_WRITE_PIXEL(_x_, _y_, _colour_) \
|
2617 |
|
|
CYG_MACRO_START \
|
2618 |
|
|
cyg_fb_linear_write_pixel_16_inl(CYG_FB_320x240x16_BASE, \
|
2619 |
|
|
CYG_FB_320x240x16_STRIDE, \
|
2620 |
|
|
_x_, _y_, _colour_); \
|
2621 |
|
|
CYG_MACRO_END
|
2622 |
|
|
#define CYG_FB_320x240x16_READ_PIXEL(_x_, _y_) \
|
2623 |
|
|
({ cyg_fb_linear_read_pixel_16_inl(CYG_FB_320x240x16_BASE, \
|
2624 |
|
|
CYG_FB_320x240x16_STRIDE, \
|
2625 |
|
|
_x_, _y_); })
|
2626 |
|
|
…
|
2627 |
|
|
|
2628 |
|
|
|
2629 |
|
|
All of the drawing primitives have variants for the common display
|
2630 |
|
|
depths and layouts: 1le, 1be, 2le, 2be, 4le, 4be, 8, 16 and 32. The
|
2631 |
|
|
inlines take the framebuffer memory base address as the first
|
2632 |
|
|
argument, and the stride in bytes as the second. Similarly there are
|
2633 |
|
|
default definitions of the true colour primitives for
|
2634 |
|
|
8BPP_TRUE_332, 16BPP_TRUE_565,
|
2635 |
|
|
16BPP_TRUE_555, and 32BPP_TRUE_0888:
|
2636 |
|
|
|
2637 |
|
|
|
2638 |
|
|
#define CYG_FB_320x240x16_MAKE_COLOUR(_r_, _g_, _b_) \
|
2639 |
|
|
({ CYG_FB_MAKE_COLOUR_16BPP_TRUE_565(_r_, _g_, _b_); })
|
2640 |
|
|
#define CYG_FB_320x240x16_BREAK_COLOUR(_colour_, _r_, _g_, _b_) \
|
2641 |
|
|
CYG_MACRO_START \
|
2642 |
|
|
CYG_FB_BREAK_COLOUR_16BPP_TRUE_565(_colour_, _r_, _g_, _b_); \
|
2643 |
|
|
CYG_MACRO_END
|
2644 |
|
|
|
2645 |
|
|
|
2646 |
|
|
These default definitions assume the most common layout of colours
|
2647 |
|
|
within a pixel value, so for
|
2648 |
|
|
example CYG_FB_MAKE_COLOUR_16BPP_TRUE_565 assumes
|
2649 |
|
|
bits 0 to 4 hold the blue intensity, bits 5 to 10 the green, and bits
|
2650 |
|
|
11 to 15 the red.
|
2651 |
|
|
|
2652 |
|
|
|
2653 |
|
|
If the hardware does not implement a linear framebuffer then obviously
|
2654 |
|
|
writing the device driver will be significantly more work. The macros
|
2655 |
|
|
will have to perform the operations themselves instead of relying on
|
2656 |
|
|
generic implementations. The required functionality should be obvious,
|
2657 |
|
|
and the generic implementations can still be consulted as a reference.
|
2658 |
|
|
For complicated hardware it may be appropriate to map the macros onto
|
2659 |
|
|
function calls, rather than try to implement everything inline.
|
2660 |
|
|
|
2661 |
|
|
At the time of writing the support for linear
|
2662 |
|
|
framebuffers is incomplete. Only 8bpp, 16bpp and 32bpp depths have
|
2663 |
|
|
full support. There may also be future extensions, for example
|
2664 |
|
|
r90, r180 and
|
2665 |
|
|
r270 variants to support rotation in software, and
|
2666 |
|
|
db variants to support double-buffered displays.
|
2667 |
|
|
|
2668 |
|
|
|
2669 |
|
|
|
2670 |
|
|
|
2671 |
|
|
Iteration Macros
|
2672 |
|
|
|
2673 |
|
|
In addition to the drawing primitives the exported header file should
|
2674 |
|
|
define iteration macros:
|
2675 |
|
|
|
2676 |
|
|
|
2677 |
|
|
#define CYG_FB_320x240x16_PIXELx_VAR( _fb_, _id_) …
|
2678 |
|
|
#define CYG_FB_320x240x16_PIXELx_SET( _fb_, _id_, _x_, _y_) …
|
2679 |
|
|
#define CYG_FB_320x240x16_PIXELx_GET( _fb_, _id_, _x_, _y_) …
|
2680 |
|
|
#define CYG_FB_320x240x16_PIXELx_ADDX( _fb_, _id_, _incr_) …
|
2681 |
|
|
#define CYG_FB_320x240x16_PIXELx_ADDY( _fb_, _id_, _incr_) …
|
2682 |
|
|
#define CYG_FB_320x240x16_PIXELx_WRITE(_fb_, _id_, _colour_) …
|
2683 |
|
|
#define CYG_FB_320x240x16_PIXELx_READ( _fb_, _id_)…
|
2684 |
|
|
#define CYG_FB_320x240x16_PIXELx_FLUSHABS( _fb_, _id_, _x0_, _y0_, _w_, _h_) …
|
2685 |
|
|
#define CYG_FB_320x240x16_PIXELx_FLUSHREL( _fb_, _id_, _x0_, _y0_, _dx_, _dy_) …
|
2686 |
|
|
|
2687 |
|
|
|
2688 |
|
|
The _fb_ argument will be the identifier, in
|
2689 |
|
|
this case 320x240x16, and the
|
2690 |
|
|
_id_ will be a small number, 0 for a
|
2691 |
|
|
PIXEL0 iteration, 1 for PIXEL1,
|
2692 |
|
|
and so on. Together these two should allow unique local variable names
|
2693 |
|
|
to be constructed. Again there are default definitions of the macros
|
2694 |
|
|
in for
|
2695 |
|
|
linear framebuffers:
|
2696 |
|
|
|
2697 |
|
|
|
2698 |
|
|
#define CYG_FB_320x240x16_PIXELx_VAR( _fb_, _id_) \
|
2699 |
|
|
CYG_FB_PIXELx_VAR_16( _fb_, _id_)
|
2700 |
|
|
#define CYG_FB_320x240x16_PIXELx_SET( _fb_, _id_, _x_, _y_) \
|
2701 |
|
|
CYG_MACRO_START \
|
2702 |
|
|
CYG_FB_PIXELx_SET_16( _fb_, _id_, \
|
2703 |
|
|
CYG_FB_320x240x16_BASE, \
|
2704 |
|
|
320, _x_, _y_); \
|
2705 |
|
|
CYG_MACRO_END
|
2706 |
|
|
|
2707 |
|
|
|
2708 |
|
|
The linear SET and GET macros
|
2709 |
|
|
take base and stride information. The ADDX and
|
2710 |
|
|
ADDY macros only need the stride. By convention
|
2711 |
|
|
most of the macros are wrapped in
|
2712 |
|
|
CYG_MACRO_START/CYG_MACRO_END or
|
2713 |
|
|
({/}) pairs, allowing debug code
|
2714 |
|
|
to be inserted if necessary. However the _VAR macro
|
2715 |
|
|
must not be wrapped in this way: its purpose is to define one or more
|
2716 |
|
|
local variables; wrapping the macro would declare the variables in a
|
2717 |
|
|
new scope, inaccessible to the other macros.
|
2718 |
|
|
|
2719 |
|
|
|
2720 |
|
|
Again for non-linear framebuffers it will be necessary to implement
|
2721 |
|
|
these macros fully rather than rely on generic implementations, but
|
2722 |
|
|
the generic versions can be consulted as a reference.
|
2723 |
|
|
|
2724 |
|
|
|
2725 |
|
|
|
2726 |
|
|
|
2727 |
|
|
The cyg_fb declaration
|
2728 |
|
|
|
2729 |
|
|
Finally there should be an export of the
|
2730 |
|
|
cyg_fb structure or structures. Typically
|
2731 |
|
|
this uses the _STRUCT parameter, reducing the
|
2732 |
|
|
possibility of an accidental mismatch between the macro and function APIs:
|
2733 |
|
|
|
2734 |
|
|
|
2735 |
|
|
extern cyg_fb CYG_FB_320x240x16_STRUCT;
|
2736 |
|
|
|
2737 |
|
|
|
2738 |
|
|
|
2739 |
|
|
|
2740 |
|
|
|
2741 |
|
|
|
2742 |
|
|
Driver-Specific Source Code
|
2743 |
|
|
|
2744 |
|
|
Exporting parameters and macros in a header file is not enough. It is
|
2745 |
|
|
also necessary to actually define the cyg_fb
|
2746 |
|
|
structure or structures, and to provide hardware-specific versions of
|
2747 |
|
|
the control operations. For non-linear framebuffers it will also be
|
2748 |
|
|
necessary to provide the drawing functions. There is a utility macro
|
2749 |
|
|
CYG_FB_FRAMEBUFFER for instantiating a
|
2750 |
|
|
cyg_fb structure. Drivers may ignore this
|
2751 |
|
|
macro and do the work themselves, but at an increased risk of
|
2752 |
|
|
compatibility problems with future versions of the generic code.
|
2753 |
|
|
|
2754 |
|
|
|
2755 |
|
|
CYG_FB_FRAMEBUFFER(CYG_FB_320x240x16_STRUCT,
|
2756 |
|
|
CYG_FB_320x240x16_DEPTH,
|
2757 |
|
|
CYG_FB_320x240x16_FORMAT,
|
2758 |
|
|
CYG_FB_320x240x16_WIDTH,
|
2759 |
|
|
CYG_FB_320x240x16_HEIGHT,
|
2760 |
|
|
CYG_FB_320x240x16_VIEWPORT_WIDTH,
|
2761 |
|
|
CYG_FB_320x240x16_VIEWPORT_HEIGHT,
|
2762 |
|
|
CYG_FB_320x240x16_BASE,
|
2763 |
|
|
CYG_FB_320x240x16_STRIDE,
|
2764 |
|
|
CYG_FB_320x240x16_FLAGS0,
|
2765 |
|
|
CYG_FB_320x240x16_FLAGS1,
|
2766 |
|
|
CYG_FB_320x240x16_FLAGS2,
|
2767 |
|
|
CYG_FB_320x240x16_FLAGS3,
|
2768 |
|
|
0, 0, 0, 0, // fb_driver0 -> fb_driver3
|
2769 |
|
|
&cyg_ipaq_fb_on,
|
2770 |
|
|
&cyg_ipaq_fb_off,
|
2771 |
|
|
&cyg_ipaq_fb_ioctl,
|
2772 |
|
|
&cyg_fb_nop_synch,
|
2773 |
|
|
&cyg_fb_nop_read_palette,
|
2774 |
|
|
&cyg_fb_nop_write_palette,
|
2775 |
|
|
&cyg_fb_dev_make_colour_16bpp_true_565,
|
2776 |
|
|
&cyg_fb_dev_break_colour_16bpp_true_565,
|
2777 |
|
|
&cyg_fb_linear_write_pixel_16,
|
2778 |
|
|
&cyg_fb_linear_read_pixel_16,
|
2779 |
|
|
&cyg_fb_linear_write_hline_16,
|
2780 |
|
|
&cyg_fb_linear_write_vline_16,
|
2781 |
|
|
&cyg_fb_linear_fill_block_16,
|
2782 |
|
|
&cyg_fb_linear_write_block_16,
|
2783 |
|
|
&cyg_fb_linear_read_block_16,
|
2784 |
|
|
&cyg_fb_linear_move_block_16,
|
2785 |
|
|
0, 0, 0, 0 // fb_spare0 -> fb_spare3
|
2786 |
|
|
);
|
2787 |
|
|
|
2788 |
|
|
|
2789 |
|
|
The first 13 arguments to the macro correspond to the device
|
2790 |
|
|
parameters. The next four are arbitrary CYG_ADDRWORD
|
2791 |
|
|
values for use by the device driver. Typically these are used to share
|
2792 |
|
|
on/off/ioctl functions between multiple
|
2793 |
|
|
cyg_fb structure. They are followed by
|
2794 |
|
|
function pointers: on/off/ioctl control; double buffer synch; palette
|
2795 |
|
|
management; true colour support; and the drawing primitives.
|
2796 |
|
|
nop versions of the on, off, ioctl, synch, palette
|
2797 |
|
|
management and true colour functions are provided by the generic
|
2798 |
|
|
framebuffer package, and often these arguments to the
|
2799 |
|
|
CYG_FB_FRAMEBUFFER macro will be discarded
|
2800 |
|
|
at compile-time because the relevant CDL interface is not implemented.
|
2801 |
|
|
The final four arguments are currently unused and should be 0. They
|
2802 |
|
|
are intended for future expansion, with a value of 0 indicating that a
|
2803 |
|
|
device driver does not implement non-core functionality.
|
2804 |
|
|
|
2805 |
|
|
|
2806 |
|
|
As with the macros there are default implementations of the true
|
2807 |
|
|
colour primitives for 8bpp_true_332,
|
2808 |
|
|
16bpp_true_565, 16bpp_true_555
|
2809 |
|
|
and 32bpp_true_0888, assuming the most common
|
2810 |
|
|
layout for these colour modes. There are also default
|
2811 |
|
|
implementations of the drawing primitives for linear framebuffers,
|
2812 |
|
|
with variants for the common display depths and layouts. Obviously
|
2813 |
|
|
non-linear framebuffers will need rather more work.
|
2814 |
|
|
|
2815 |
|
|
|
2816 |
|
|
Typically a true colour or grey scale framebuffer device driver will
|
2817 |
|
|
have to implement just three hardware-specific functions:
|
2818 |
|
|
|
2819 |
|
|
|
2820 |
|
|
int
|
2821 |
|
|
cyg_ipaq_fb_on(cyg_fb* fb)
|
2822 |
|
|
{
|
2823 |
|
|
…
|
2824 |
|
|
}
|
2825 |
|
|
|
2826 |
|
|
int
|
2827 |
|
|
cyg_ipaq_fb_off(cyg_fb* fb)
|
2828 |
|
|
{
|
2829 |
|
|
…
|
2830 |
|
|
}
|
2831 |
|
|
|
2832 |
|
|
int
|
2833 |
|
|
cyg_ipaq_fb_ioctl(cyg_fb* fb, cyg_ucount16 key, void* data, size_t* len)
|
2834 |
|
|
{
|
2835 |
|
|
int result;
|
2836 |
|
|
|
2837 |
|
|
switch(key) {
|
2838 |
|
|
case CYG_FB_IOCTL_BLANK_GET: …
|
2839 |
|
|
…
|
2840 |
|
|
default: result = ENOSYS; break;
|
2841 |
|
|
}
|
2842 |
|
|
return result;
|
2843 |
|
|
}
|
2844 |
|
|
|
2845 |
|
|
|
2846 |
|
|
These control operations are entirely hardware-specific and cannot be
|
2847 |
|
|
implemented by generic code. Paletted displays will need two more
|
2848 |
|
|
functions, again hardware-specific:
|
2849 |
|
|
|
2850 |
|
|
|
2851 |
|
|
void
|
2852 |
|
|
cyg_pcvga_fb_read_palette(cyg_fb* fb, cyg_ucount32 first, cyg_ucount32 len,
|
2853 |
|
|
void* data)
|
2854 |
|
|
{
|
2855 |
|
|
…
|
2856 |
|
|
}
|
2857 |
|
|
|
2858 |
|
|
void
|
2859 |
|
|
cyg_pcvga_fb_write_palette(cyg_fb* fb, cyg_ucount32 first, cyg_ucount32 len,
|
2860 |
|
|
const void* data, cyg_ucount16 when)
|
2861 |
|
|
{
|
2862 |
|
|
…
|
2863 |
|
|
}
|
2864 |
|
|
|
2865 |
|
|
|
2866 |
|
|
|
2867 |
|
|
|
2868 |
|
|
Future Expansion
|
2869 |
|
|
|
2870 |
|
|
As has been mentioned before framebuffer hardware varies widely. The
|
2871 |
|
|
design of a generic framebuffer API requires complicated trade-offs
|
2872 |
|
|
between efficiency, ease of use, ease of porting, and still supporting
|
2873 |
|
|
a very wide range of hardware. To some extent this requires a lowest
|
2874 |
|
|
common denominator approach, but the design allows for some future
|
2875 |
|
|
expansion and optional support for more advanced features like
|
2876 |
|
|
hardware acceleration.
|
2877 |
|
|
|
2878 |
|
|
|
2879 |
|
|
The most obvious route for expansion is the ioctl
|
2880 |
|
|
interface. Device drivers can define their own keys, values
|
2881 |
|
|
0x8000 and higher, for any operation. Alternatively
|
2882 |
|
|
a device driver does not have to implement just the interface provided
|
2883 |
|
|
by the generic framebuffer package: additional functions and macros
|
2884 |
|
|
can be exported as required.
|
2885 |
|
|
|
2886 |
|
|
|
2887 |
|
|
Currently there are only a small number of ioctl
|
2888 |
|
|
operations. Additional ones may get added in future, for example to
|
2889 |
|
|
support a hardware mouse cursor, but only in cases where the
|
2890 |
|
|
functionality is likely to be provided by a significant number of
|
2891 |
|
|
framebuffer devices. Adding new generic functionality adds to the
|
2892 |
|
|
maintenance overhead of both code and documentation. When a new
|
2893 |
|
|
generic ioctl operation is added there will
|
2894 |
|
|
usually also be one or more new flags, so that device drivers can
|
2895 |
|
|
indicate they support the functionality. At the time of writing only
|
2896 |
|
|
12 of the 32 FLAGS0 flags are used, and a further
|
2897 |
|
|
96 are available in FLAGS1,
|
2898 |
|
|
FLAGS2 and FLAGS3.
|
2899 |
|
|
|
2900 |
|
|
|
2901 |
|
|
Another route for future expansion is the four spare arguments to the
|
2902 |
|
|
CYG_FB_FRAMEBUFFER macro. As an example of how
|
2903 |
|
|
these may get used in future, consider support for 3d hardware
|
2904 |
|
|
acceleration. One of the spare fields would become another table of
|
2905 |
|
|
function pointers to the various accelerators, or possibly a
|
2906 |
|
|
structure. A FLAGS0 flag would indicate that the
|
2907 |
|
|
device driver implements such functionality.
|
2908 |
|
|
|
2909 |
|
|
|
2910 |
|
|
Other forms of expansion such as defining a new standard drawing
|
2911 |
|
|
primitive would be more difficult, since this would normally involve
|
2912 |
|
|
changing the CYG_FB_FRAMEBUFFER macro. Such
|
2913 |
|
|
expansion should not be necessary because the existing primitives
|
2914 |
|
|
provide all reasonable core functionality. Instead other packages such
|
2915 |
|
|
as graphics libraries can work on top of the existing primitives.
|
2916 |
|
|
|
2917 |
|
|
|
2918 |
|
|
|
2919 |
|
|
|
2920 |
|
|
|
2921 |
|
|
|
2922 |
|
|
|
2923 |
|
|
|