Changeset 10222 in project


Ignore:
Timestamp:
03/31/08 22:49:22 (12 years ago)
Author:
hans
Message:

extended directfb egg documentation

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/directfb

    r9897 r10222  
    3232 Copyright (c) 2007, 2008  Hans Bulfone <jsb@nil.at>
    3333 All rights reserved.
    34 
     34 
    3535 Redistribution and use in source and binary forms, with or without
    3636 modification, are permitted provided that the following conditions are met:
    37 
     37 
    3838     * Redistributions of source code must retain the above copyright notice,
    3939       this list of conditions and the following disclaimer.
     
    4444       be used to endorse or promote products derived from this software
    4545       without specific prior written permission.
    46 
     46 
    4747 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    4848 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
     
    223223=== DirectFB record types
    224224
    225 DirectFB also defines some simple record-types (represented as C structs
    226 of course) like {{DFBPoint}} or {{DFBRectangle}}.  There are also a few
     225DirectFB also defines some simple record-types (represented as C structs)
     226like {{DFBPoint}} or {{DFBRectangle}}.  There are also a few
    227227more complicated types like {{DFBSurfaceDescription}} with optional fields.
    228228
     
    279279
    280280
     281=== Error reporting
     282
     283Errors in the DirectFB API are usually reported as {{(exn directfb)}}
     284conditions.
     285
     286The {{directfb}}-part has a {{code}} property containing the DirectFB
     287error code (a symbol) and a {{function}} property containg a symbol
     288naming the function or method that reported the error.
     289
     290The {{exn}}-part has a {{message}} property with the same information
     291in user-parseable string form.
     292
     293In some functions however, a few "errors" reported by DirectFB don't
     294cause a condition to be signalled but rather a special value to be
     295returned.  For example, {{dfbeb-get-event}} simply returns {{#f}}
     296when there is no event available instead of signalling an error.
     297
     298<enscript highlight=scheme>(dfb-error? x [code] [function])</enscript>
     299
     300Returns {{#t}} if {{x}} is a {{directfb}}-condition, optionally with the
     301given {{code}} and {{function}} properties (compared using {{eq?}} as
     302they should always be symbols).
     303
     304<enscript highlight=scheme>(dfb-error-code exn)</enscript>
     305
     306Returns the value of the {{code}} property of {{exn}}, which must be a
     307{{directfb}}-condition.
     308
     309<enscript highlight=scheme>(dfb-error-function exn)</enscript>
     310
     311Returns the value of the {{function}} property of {{exn}}, which must be a
     312{{directfb}}-condition.
     313
     314
     315=== Convenience functions
     316
     317The following utility functions are provided beyond the DirectFB API:
     318
     319==== dfb-initialize
     320
     321<enscript highlight=scheme>(dfb-initialize [coop-level: coop-level])</enscript>
     322
     323Calls {{dfb-init}}, {{dfb-create}} and, if {{coop-level}} is given,
     324{{dfb-set-cooperative-level}}.  If the latter call fails with {{ACCESSDENIED}},
     325the error is ignored (as suggested by the DirectFB documentation to allow
     326a fullscreen application to run in a window if required).  Other errors
     327are reported as usual.  This function returns the DirectFB super-interface.
     328Valid values for {{coop-level}} are: {{'NORMAL}}, {{'FULLSCREEN}} and {{'EXCLUSIVE}}.
     329
     330==== dfb-load-image-to-surface
     331
     332<enscript highlight=scheme>(dfb-load-image-to-surface dfb filename)</enscript>
     333
     334Loads the image file denoted by {{filename}} into a new surface and returns it.
     335
     336==== dfbeb-wait/get-event
     337
     338<enscript highlight=scheme>(dfbeb-wait/get-event eb [timeout])</enscript>
     339
     340Returns the next event from the event buffer {{eb}}, waiting at most
     341{{timeout}} seconds if no event is immediately available (or indefinitely if
     342{{timeout}} is not given or {{#f}}).
     343
     344Returns the event or {{#f}} if the timeout is reached.
     345
     346This function allows other {{srfi-18}} threads to run while it waits for an
     347event which is implemented with a simple polling loop using
     348{{(thread-sleep! .01)}} between polls.  Also the {{timeout}} parameter is
     349only a rough estimate as it is simply divided by {{0.01}} to get the number
     350of iterations.  This function is meant to be called with small values for
     351{{timeout}}, like {{0.01}} to {{0.1}}.
     352
     353If you need more precision, {{dfbeb-create-file-descriptor}} might be useful
     354but its usage isn't really supported by the directfb egg at the moment.
     355
     356==== dfbvp-play-to/flip
     357
     358<enscript highlight=scheme>(dfbvp-play-to/flip vp dest dest-rect)</enscript>
     359
     360A wrapper around {{dfbvp-play-to}} with a callback that {{Flip()}}s the
     361destination surface after every video frame.
     362
     363This function is provided because callbacks for {{dfbvp-play-to}} must be
     364implemented in C as they are called from a separate OS-level thread and
     365flipping is by far the most common operation a frame callback has to perform.
     366
     367
    281368== Version history
    282369
Note: See TracChangeset for help on using the changeset viewer.