Editing page: Outdated egg! - The CHICKEN Scheme wiki

You can edit this page using wiki syntax for markup.

Article contents:

== Outdated egg!

This is an egg for CHICKEN 3, the unsupported old release.  You're almost certainly looking for [[/eggref/4/directfb|the CHICKEN 4 version of this egg]], if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the [[https://wiki.call-cc.org/chicken-projects/egg-index-4.html|egg index]]. Otherwise, please consider porting this egg to the current version of CHICKEN.

[[tags:eggs]]

[[toc:]]

== directfb

=== Introduction

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>

=== Examples

See [[http://www.nil.at/software/dfb-examples]] for a few examples of using
DirectFB from Chicken.

=== Authors

Hans Bulfone <jsb@nil.at>

=== License

Copyright (c) 2007, 2008  Hans Bulfone <jsb@nil.at>
 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.

=== Requirements

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.

=== Usage

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.

==== Initialization

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.

==== DirectFB interfaces

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

<enscript highlight=c>surface->FillRectangle(surface, x, y, w, h);</enscript>

in C, you write

<enscript highlight=scheme>(dfbs-fill-rectangle surface x y w h)</enscript>

in Scheme.

The following table shows the mapping between DirectFB interface types and
scheme function name prefixes (like {{dfbs}} in the previous example):

<table>
<tr><th>DirectFB interface</th><th>Scheme prefix</th></tr>
<tr><td>{{IDirectFB}}</td><td>{{dfb}}</td></tr>
<tr><td>{{IDirectFBScreen}}</td><td>{{dfbscr}}</td></tr>
<tr><td>{{IDirectFBDisplayLayer}}</td><td>{{dfbdl}}</td></tr>
<tr><td>{{IDirectFBWindow}}</td><td>{{dfbw}}</td></tr>
<tr><td>{{IDirectFBSurface}}</td><td>{{dfbs}}</td></tr>
<tr><td>{{IDirectFBInputDevice}}</td><td>{{dfbid}}</td></tr>
<tr><td>{{IDirectFBEventBuffer}}</td><td>{{dfbeb}}</td></tr>
<tr><td>{{IDirectFBImageProvider}}</td><td>{{dfbip}}</td></tr>
<tr><td>{{IDirectFBVideoProvider}}</td><td>{{dfbvp}}</td></tr>
<tr><td>{{IDirectFBFont}}</td><td>{{dfbf}}</td></tr>
</table>

===== The super interface

You obtain the main DirectFB interface (also called the super interface)
like this:

<enscript highlight=scheme>(dfb-create)</enscript>

All other DirectFB objects are constructed by methods of this interface
(or methods of objects constructed by those methods).

===== Memory management

If you are done with a DirectFB object, you release it with

<enscript highlight=scheme>(dfb-release OBJ)</enscript>

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:

<enscript highlight=scheme>
(with-dfb-objects ((VAR1 INIT1)
                   (VAR2 INIT2)
                   ...)
  BODY...)
</enscript>

This expands to the following code:

<enscript highlight=scheme>
(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)))))
</enscript>

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 {{VAR}}s will be {{#f}}, they are not re-initialized.

The second macro is:

this expands into:

<enscript highlight=scheme>
(let ((GENSYM VAR))
  (set! VAR #f)
  GENSYM)
</enscript>

This is useful if you want to return a DirectFB-object from a function:

<enscript highlight=scheme>
(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)))
</enscript>

==== 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 {{blob}}s (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:

===== Constructor

This creates a new record instance.  Required slots are passed as normal
arguments, optional slots as keyword arguments.

===== Type predicate

Returns {{#t}} if {{X}} is an instance of the record-type {{dfb-TYPE}},
{{#f}} otherwise.

===== Accessors

Returns the value of {{SLOT}} of {{OBJ}}, which must be an instance of
the record-type {{dfb-TYPE}}.

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}}:

<enscript highlight=scheme>(dfb-nothing)</enscript>

Returns the special "unspecified" value which means that the value
of an optional slot is not specified.

<enscript highlight=scheme>(dfb-nothing? X)</enscript>

Returns {{#t}} if {{X}} is the special "unspecified" value, {{#f}}
otherwise.

===== Printer

A record printer is provided for all DirectFB record-types, so they
can be easily printed for debugging purposes.

==== Error reporting

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.

<enscript highlight=scheme>(dfb-error? x [code] [function])</enscript>

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).

<enscript highlight=scheme>(dfb-error-code exn)</enscript>

Returns the value of the {{code}} property of {{exn}}, which must be a
{{directfb}}-condition.

<enscript highlight=scheme>(dfb-error-function exn)</enscript>

Returns the value of the {{function}} property of {{exn}}, which must be a
{{directfb}}-condition.

==== Convenience functions

The following utility functions are provided beyond the DirectFB API:

===== dfb-initialize

<enscript highlight=scheme>(dfb-initialize [coop-level: coop-level])</enscript>

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

<enscript highlight=scheme>(dfb-load-image-to-surface dfb filename)</enscript>

Loads the image file denoted by {{filename}} into a new surface and returns it.

===== dfbeb-wait/get-event

<enscript highlight=scheme>(dfbeb-wait/get-event eb [timeout])</enscript>

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

<enscript highlight=scheme>(dfbvp-play-to/flip vp dest dest-rect)</enscript>

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.

=== Version history

==== 0.8

* Initial release.

Description of your changes:

I would like to authenticate

Authentication

Username:Password:

Spam control

What do you get when you subtract 21 from 0?