source: project/wiki/directfb @ 10360

Last change on this file since 10360 was 10360, checked in by hans, 12 years ago

updated directfb documentation

File size: 12.3 KB
Line 
1[[tags:eggs]]
2
3[[toc:]]
4
5== Introduction
6
7A binding for the DirectFB library.  From its homepage, [[http://www.directfb.org/]]:
8<blockquote>
9DirectFB is a thin library that provides hardware graphics
10acceleration, input device handling and abstraction, integrated
11windowing system with support for translucent windows and multiple
12display layers, not only on top of the Linux Framebuffer Device. It is
13a complete hardware abstraction layer with software fallbacks for
14every graphics operation that is not supported by the underlying
15hardware. DirectFB adds graphical power to embedded systems and sets a
16new standard for graphics under Linux.
17</blockquote>
18
19
20== Examples
21
22See [[http://www.nil.at/software/dfb-examples]] for a few examples of using
23DirectFB from Chicken.
24
25
26== Authors
27
28Hans Bulfone <jsb@nil.at>
29
30
31== License
32
33 Copyright (c) 2007, 2008  Hans Bulfone <jsb@nil.at>
34 All rights reserved.
35 
36 Redistribution and use in source and binary forms, with or without
37 modification, are permitted provided that the following conditions are met:
38 
39     * Redistributions of source code must retain the above copyright notice,
40       this list of conditions and the following disclaimer.
41     * Redistributions in binary form must reproduce the above copyright
42       notice, this list of conditions and the following disclaimer in the
43       documentation and/or other materials provided with the distribution.
44     * Neither the name of the author nor the names of his contributors may
45       be used to endorse or promote products derived from this software
46       without specific prior written permission.
47 
48 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
49 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
50 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
51 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
52 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
53 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
54 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
55 OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
56 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
57 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
58 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
59
60DirectFB itself is licensed under LGPL-2 or later.
61
62
63== Requirements
64
65This egg requires the {{dollar}} egg and at least version 1.1.1 of DirectFB.
66The setup script uses {{pkg-config}} to get the correct compiler and linker
67flags for DirectFB so you'll need that as well.
68
69
70== Usage
71
72The following sections describe the C to Scheme mapping and a few
73convenience functions.  I'm afraid, for now, you have to check out
74the source code and the C API documentation at
75[[http://www.directfb.org/docs/DirectFB_Reference_1_1/]]
76for information about most of the functions that are provided.
77
78
79=== Initialization
80
81Before any other DirectFB function can be called, the library must be
82initialized:
83
84<enscript highlight=scheme>(dfb-init)</enscript>
85
86There is also a convenience function called {{(dfb-initialize)}} which
87does this and a few other things.  This function will be described later.
88
89
90=== DirectFB interfaces
91
92In DirectFB, all functionality is available through interfaces which are
93C structs containing function pointers.
94
95In Scheme, these interfaces are represented as record-instances that
96contain a foreign-pointer to the C struct.  For each function pointer in
97the C struct ("method") a scheme function is provided.  E.g. when you
98would write
99
100<enscript highlight=c>surface->FillRectangle(surface, x, y, w, h);</enscript>
101
102in C, you write
103
104<enscript highlight=scheme>(dfbs-fill-rectangle surface x y w h)</enscript>
105
106in Scheme.
107
108The following table shows the mapping between DirectFB interface types and
109scheme function name prefixes (like {{dfbs}} in the previous example):
110
111<table>
112<tr><th>DirectFB interface</th><th>Scheme prefix</th></tr>
113<tr><td>{{IDirectFB}}</td><td>{{dfb}}</td></tr>
114<tr><td>{{IDirectFBScreen}}</td><td>{{dfbscr}}</td></tr>
115<tr><td>{{IDirectFBDisplayLayer}}</td><td>{{dfbdl}}</td></tr>
116<tr><td>{{IDirectFBWindow}}</td><td>{{dfbw}}</td></tr>
117<tr><td>{{IDirectFBSurface}}</td><td>{{dfbs}}</td></tr>
118<tr><td>{{IDirectFBInputDevice}}</td><td>{{dfbid}}</td></tr>
119<tr><td>{{IDirectFBEventBuffer}}</td><td>{{dfbeb}}</td></tr>
120<tr><td>{{IDirectFBImageProvider}}</td><td>{{dfbip}}</td></tr>
121<tr><td>{{IDirectFBVideoProvider}}</td><td>{{dfbvp}}</td></tr>
122<tr><td>{{IDirectFBFont}}</td><td>{{dfbf}}</td></tr>
123</table>
124
125
126==== The super interface
127
128You obtain the main DirectFB interface (also called the super interface)
129like this:
130
131<enscript highlight=scheme>(dfb-create)</enscript>
132
133All other DirectFB objects are constructed by methods of this interface
134(or methods of objects constructed by those methods).
135
136
137==== Memory management
138
139If you are done with a DirectFB object, you release it with
140
141<enscript highlight=scheme>(dfb-release OBJ)</enscript>
142
143No finalizers are registered, so if you forget to call {{dfb-release}}
144you leak memory.
145
146To make things easier for common cases, two macros are provided:
147
148<enscript highlight=scheme>
149(with-dfb-objects ((VAR1 INIT1)
150                   (VAR2 INIT2)
151                   ...)
152  BODY...)
153</enscript>
154
155This expands to the following code:
156
157<enscript highlight=scheme>
158(let ((VAR1 #f)
159      (VAR2 #f)
160      ...)
161  (dynamic-wind
162      void
163      (lambda ()
164        (set! VAR1 INIT1)
165        (set! VAR2 INIT2)
166        ...
167        BODY...)
168      (lambda ()
169        ...
170        (when VAR2
171          (dfb-release VAR2)
172          (set! VAR2 #f))
173        (when VAR1
174          (dfb-release VAR1)
175          (set! VAR1 #f)))))
176</enscript>
177
178This ensures that the DirectFB objects are released when execution leaves the
179dynamic context of the {{BODY}} (either because it returns normally or because
180an exception has been thrown or a continuation captured outside of the {{BODY}}
181is invoked).
182
183If you use {{call/cc}} to capture a continuation inside the {{BODY}} and
184re-enter it later, the {{VAR}}s will be {{#f}}, they are not re-initialized.
185
186The second macro is:
187
188<enscript highlight=scheme>
189(dfb-give VAR)
190</enscript>
191
192this expands into:
193
194<enscript highlight=scheme>
195(let ((GENSYM VAR))
196  (set! VAR #f)
197  GENSYM)
198</enscript>
199
200This is useful if you want to return a DirectFB-object from a function:
201
202<enscript highlight=scheme>
203(define (create-my-ueber-cool-surface dfb w h)
204  (with-dfb-objects ((surf (dfb-create-surface dfb width: w height: h)))
205
206    ;; draw a cool picture on the surface or something :)
207    ;; if e.g. an exception is thrown now the surface will be
208    ;; properly released.
209
210    ;; return the surface to the caller, don't release it
211    (dfb-give surf)))
212
213(define (do-somthing-cool dfb)
214  (with-dfb-objects ((surf1 (create-my-ueber-cool-surface dfb 100 100))
215                     (surf2 (create-an-even-cooler-surface dfb 200 200)))
216    ;; do something with those surfaces
217    ;; if we don't use dfb-give, the surfaces are released at the end
218    ;; of the function.  we can also release them earlier:
219    (dfb-release (dfb-give surf1))
220
221    ;; we can even re-use surf1 now if we want:
222    (set! surf1 (create-another-surface dfb 300 300))
223    ;; the new surf1 will be released after this (as well as surf2)
224    (void)))
225</enscript>
226
227
228=== DirectFB record types
229
230DirectFB also defines some simple record-types (represented as C structs)
231like {{DFBPoint}} or {{DFBRectangle}}.  There are also a few
232more complicated types like {{DFBSurfaceDescription}} with optional fields.
233
234Those structs are represented as {{blob}}s (containing the C structure data),
235wrapped in Chicken record-types.  They are managed by the normal garbage
236collector, so you don't need to release them.
237
238For each structure the following is provided:
239
240==== Constructor
241
242<enscript highlight=scheme>(make-dfb-TYPE REQ1 REQ2 opt1: OPT1 opt2: OPT2)</enscript>
243
244This creates a new record instance.  Required slots are passed as normal
245arguments, optional slots as keyword arguments.
246
247==== Type predicate
248
249<enscript highlight=scheme>(dfb-TYPE? X)</enscript>
250
251Returns {{#t}} if {{X}} is an instance of the record-type {{dfb-TYPE}},
252{{#f}} otherwise.
253
254==== Accessors
255
256<enscript highlight=scheme>(dfb-TYPE-SLOT OBJ)</enscript>
257
258Returns the value of {{SLOT}} of {{OBJ}}, which must be an instance of
259the record-type {{dfb-TYPE}}.
260
261<enscript highlight=scheme>(dfb-TYPE-SLOT-set! OBJ VAL)</enscript>
262
263Sets {{SLOT}} of {{OBJ}} to {{VAL}}.  {{OBJ}} must be an instance of
264the record-type {{dfb-TYPE}}.
265
266For optional slots there is a special "unspecified" value that
267can be passed to {{dfb-TYPE-SLOT-set!}} or returned by
268{{dfb-TYPE-SLOT}}:
269
270<enscript highlight=scheme>(dfb-nothing)</enscript>
271
272Returns the special "unspecified" value which means that the value
273of an optional slot is not specified.
274
275<enscript highlight=scheme>(dfb-nothing? X)</enscript>
276
277Returns {{#t}} if {{X}} is the special "unspecified" value, {{#f}}
278otherwise.
279
280==== Printer
281
282A record printer is provided for all DirectFB record-types, so they
283can be easily printed for debugging purposes.
284
285
286=== Error reporting
287
288Errors in the DirectFB API are usually reported as {{(exn directfb)}}
289conditions.
290
291The {{directfb}}-part has a {{code}} property containing the DirectFB
292error code (a symbol) and a {{function}} property containg a symbol
293naming the function or method that reported the error.
294
295The {{exn}}-part has a {{message}} property with the same information
296in user-parseable string form.
297
298In some functions however, a few "errors" reported by DirectFB don't
299cause a condition to be signalled but rather a special value to be
300returned.  For example, {{dfbeb-get-event}} simply returns {{#f}}
301when there is no event available instead of signalling an error.
302
303<enscript highlight=scheme>(dfb-error? x [code] [function])</enscript>
304
305Returns {{#t}} if {{x}} is a {{directfb}}-condition, optionally with the
306given {{code}} and {{function}} properties (compared using {{eq?}} as
307they should always be symbols).
308
309<enscript highlight=scheme>(dfb-error-code exn)</enscript>
310
311Returns the value of the {{code}} property of {{exn}}, which must be a
312{{directfb}}-condition.
313
314<enscript highlight=scheme>(dfb-error-function exn)</enscript>
315
316Returns the value of the {{function}} property of {{exn}}, which must be a
317{{directfb}}-condition.
318
319
320=== Convenience functions
321
322The following utility functions are provided beyond the DirectFB API:
323
324==== dfb-initialize
325
326<enscript highlight=scheme>(dfb-initialize [coop-level: coop-level])</enscript>
327
328Calls {{dfb-init}}, {{dfb-create}} and, if {{coop-level}} is given,
329{{dfb-set-cooperative-level}}.  If the latter call fails with {{ACCESSDENIED}},
330the error is ignored (as suggested by the DirectFB documentation to allow
331a fullscreen application to run in a window if required).  Other errors
332are reported as usual.  This function returns the DirectFB super-interface.
333Valid values for {{coop-level}} are: {{'NORMAL}}, {{'FULLSCREEN}} and {{'EXCLUSIVE}}.
334
335==== dfb-load-image-to-surface
336
337<enscript highlight=scheme>(dfb-load-image-to-surface dfb filename)</enscript>
338
339Loads the image file denoted by {{filename}} into a new surface and returns it.
340
341==== dfbeb-wait/get-event
342
343<enscript highlight=scheme>(dfbeb-wait/get-event eb [timeout])</enscript>
344
345Returns the next event from the event buffer {{eb}}, waiting at most
346{{timeout}} seconds if no event is immediately available (or indefinitely if
347{{timeout}} is not given or {{#f}}).
348
349Returns the event or {{#f}} if the timeout is reached.
350
351This function allows other {{srfi-18}} threads to run while it waits for an
352event which is implemented with a simple polling loop using
353{{(thread-sleep! .01)}} between polls.  Also the {{timeout}} parameter is
354only a rough estimate as it is simply divided by {{0.01}} to get the number
355of iterations.  This function is meant to be called with small values for
356{{timeout}}, like {{0.01}} to {{0.1}}.
357
358If you need more precision, {{dfbeb-create-file-descriptor}} might be useful
359but its usage isn't really supported by the directfb egg at the moment.
360
361==== dfbvp-play-to/flip
362
363<enscript highlight=scheme>(dfbvp-play-to/flip vp dest dest-rect)</enscript>
364
365A wrapper around {{dfbvp-play-to}} with a callback that {{Flip()}}s the
366destination surface after every video frame.
367
368This function is provided because callbacks for {{dfbvp-play-to}} must be
369implemented in C as they are called from a separate OS-level thread and
370flipping is by far the most common operation a frame callback has to perform.
371
372
373== Version history
374
375=== 0.8
376
377* Initial release.
Note: See TracBrowser for help on using the repository browser.