You are looking at historical revision 10360 of this page. It may differ significantly from its current revision.
- Version history
A binding for the DirectFB library. From its homepage, http://www.directfb.org/: <blockquote> DirectFB is a thin library that provides hardware graphics acceleration, input device handling and abstraction, integrated windowing system with support for translucent windows and multiple display layers, not only on top of the Linux Framebuffer Device. It is a complete hardware abstraction layer with software fallbacks for every graphics operation that is not supported by the underlying hardware. DirectFB adds graphical power to embedded systems and sets a new standard for graphics under Linux. </blockquote>
See http://www.nil.at/software/dfb-examples for a few examples of using DirectFB from Chicken.
Hans Bulfone <firstname.lastname@example.org>
Copyright (c) 2007, 2008 Hans Bulfone <email@example.com> All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the author nor the names of his contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
DirectFB itself is licensed under LGPL-2 or later.
This egg requires the dollar egg and at least version 1.1.1 of DirectFB. The setup script uses pkg-config to get the correct compiler and linker flags for DirectFB so you'll need that as well.
The following sections describe the C to Scheme mapping and a few convenience functions. I'm afraid, for now, you have to check out the source code and the C API documentation at http://www.directfb.org/docs/DirectFB_Reference_1_1/ for information about most of the functions that are provided.
Before any other DirectFB function can be called, the library must be initialized:
There is also a convenience function called (dfb-initialize) which does this and a few other things. This function will be described later.
In DirectFB, all functionality is available through interfaces which are C structs containing function pointers.
In Scheme, these interfaces are represented as record-instances that contain a foreign-pointer to the C struct. For each function pointer in the C struct ("method") a scheme function is provided. E.g. when you would write
surface->FillRectangle(surface, x, y, w, h);
in C, you write
(dfbs-fill-rectangle surface x y w h)
The following table shows the mapping between DirectFB interface types and scheme function name prefixes (like dfbs in the previous example):
|DirectFB interface||Scheme prefix|
The super interface
You obtain the main DirectFB interface (also called the super interface) like this:
All other DirectFB objects are constructed by methods of this interface (or methods of objects constructed by those methods).
If you are done with a DirectFB object, you release it with
No finalizers are registered, so if you forget to call dfb-release you leak memory.
To make things easier for common cases, two macros are provided:
(with-dfb-objects ((VAR1 INIT1) (VAR2 INIT2) ...) BODY...)
This expands to the following code:
(let ((VAR1 #f) (VAR2 #f) ...) (dynamic-wind void (lambda () (set! VAR1 INIT1) (set! VAR2 INIT2) ... BODY...) (lambda () ... (when VAR2 (dfb-release VAR2) (set! VAR2 #f)) (when VAR1 (dfb-release VAR1) (set! VAR1 #f)))))
This ensures that the DirectFB objects are released when execution leaves the dynamic context of the BODY (either because it returns normally or because an exception has been thrown or a continuation captured outside of the BODY is invoked).
If you use call/cc to capture a continuation inside the BODY and re-enter it later, the VARs will be #f, they are not re-initialized.
The second macro is:
this expands into:
(let ((GENSYM VAR)) (set! VAR #f) GENSYM)
This is useful if you want to return a DirectFB-object from a function:
(define (create-my-ueber-cool-surface dfb w h) (with-dfb-objects ((surf (dfb-create-surface dfb width: w height: h))) ;; draw a cool picture on the surface or something :) ;; if e.g. an exception is thrown now the surface will be ;; properly released. ;; return the surface to the caller, don't release it (dfb-give surf))) (define (do-somthing-cool dfb) (with-dfb-objects ((surf1 (create-my-ueber-cool-surface dfb 100 100)) (surf2 (create-an-even-cooler-surface dfb 200 200))) ;; do something with those surfaces ;; if we don't use dfb-give, the surfaces are released at the end ;; of the function. we can also release them earlier: (dfb-release (dfb-give surf1)) ;; we can even re-use surf1 now if we want: (set! surf1 (create-another-surface dfb 300 300)) ;; the new surf1 will be released after this (as well as surf2) (void)))
DirectFB record types
DirectFB also defines some simple record-types (represented as C structs) like DFBPoint or DFBRectangle. There are also a few more complicated types like DFBSurfaceDescription with optional fields.
Those structs are represented as blobs (containing the C structure data), wrapped in Chicken record-types. They are managed by the normal garbage collector, so you don't need to release them.
For each structure the following is provided:
(make-dfb-TYPE REQ1 REQ2 opt1: OPT1 opt2: OPT2)
This creates a new record instance. Required slots are passed as normal arguments, optional slots as keyword arguments.
Returns #t if X is an instance of the record-type dfb-TYPE, #f otherwise.
Returns the value of SLOT of OBJ, which must be an instance of the record-type dfb-TYPE.
(dfb-TYPE-SLOT-set! OBJ VAL)
Sets SLOT of OBJ to VAL. OBJ must be an instance of the record-type dfb-TYPE.
For optional slots there is a special "unspecified" value that can be passed to dfb-TYPE-SLOT-set! or returned by dfb-TYPE-SLOT:
Returns the special "unspecified" value which means that the value of an optional slot is not specified.
Returns #t if X is the special "unspecified" value, #f otherwise.
A record printer is provided for all DirectFB record-types, so they can be easily printed for debugging purposes.
Errors in the DirectFB API are usually reported as (exn directfb) conditions.
The directfb-part has a code property containing the DirectFB error code (a symbol) and a function property containg a symbol naming the function or method that reported the error.
The exn-part has a message property with the same information in user-parseable string form.
In some functions however, a few "errors" reported by DirectFB don't cause a condition to be signalled but rather a special value to be returned. For example, dfbeb-get-event simply returns #f when there is no event available instead of signalling an error.
(dfb-error? x [code] [function])
Returns #t if x is a directfb-condition, optionally with the given code and function properties (compared using eq? as they should always be symbols).
Returns the value of the code property of exn, which must be a directfb-condition.
Returns the value of the function property of exn, which must be a directfb-condition.
The following utility functions are provided beyond the DirectFB API:
(dfb-initialize [coop-level: coop-level])
Calls dfb-init, dfb-create and, if coop-level is given, dfb-set-cooperative-level. If the latter call fails with ACCESSDENIED, the error is ignored (as suggested by the DirectFB documentation to allow a fullscreen application to run in a window if required). Other errors are reported as usual. This function returns the DirectFB super-interface. Valid values for coop-level are: 'NORMAL, 'FULLSCREEN and 'EXCLUSIVE.
(dfb-load-image-to-surface dfb filename)
Loads the image file denoted by filename into a new surface and returns it.
(dfbeb-wait/get-event eb [timeout])
Returns the next event from the event buffer eb, waiting at most timeout seconds if no event is immediately available (or indefinitely if timeout is not given or #f).
Returns the event or #f if the timeout is reached.
This function allows other srfi-18 threads to run while it waits for an event which is implemented with a simple polling loop using (thread-sleep! .01) between polls. Also the timeout parameter is only a rough estimate as it is simply divided by 0.01 to get the number of iterations. This function is meant to be called with small values for timeout, like 0.01 to 0.1.
If you need more precision, dfbeb-create-file-descriptor might be useful but its usage isn't really supported by the directfb egg at the moment.
(dfbvp-play-to/flip vp dest dest-rect)
A wrapper around dfbvp-play-to with a callback that Flip()s the destination surface after every video frame.
This function is provided because callbacks for dfbvp-play-to must be implemented in C as they are called from a separate OS-level thread and flipping is by far the most common operation a frame callback has to perform.
- Initial release.