| 1 |
<html lang="en"> |
|---|
| 2 |
<head> |
|---|
| 3 |
<title>DerelictSDL</title> |
|---|
| 4 |
<link rel="stylesheet" type="text/css" href="styles.css"> |
|---|
| 5 |
</head> |
|---|
| 6 |
<body> |
|---|
| 7 |
<h2>DerelictSDL</h2> |
|---|
| 8 |
DerelictSDL is a D binding to Sam Lantinga's <a href="http://www.libsdl.org/">Simple |
|---|
| 9 |
DirectMedia Layer</a>, a cross-platform multimedia library designed to provide |
|---|
| 10 |
low level access to audio, keyboard, mouse, joystick, 3D hardware via OpenGL, |
|---|
| 11 |
and 2D video framebuffer. DerelictSDL is implemented |
|---|
| 12 |
against the 1.2.x series of the SDL library. It will not work with the 1.3.x series, |
|---|
| 13 |
the version which will eventually become SDL 2. |
|---|
| 14 |
|
|---|
| 15 |
<p> |
|---|
| 16 |
The current version of DerelictSDL requires at least <tt>SDL 1.2.13</tt>. |
|---|
| 17 |
</p> |
|---|
| 18 |
|
|---|
| 19 |
<h3>Building</h3> |
|---|
| 20 |
To compile DerelictSDL only, add the <tt>DerelictSDL</tt> make target to the command line when |
|---|
| 21 |
compiling Derelict. For example, to build DerelictSDL on Windows with DMD, you would execute |
|---|
| 22 |
the following: |
|---|
| 23 |
<pre><code> |
|---|
| 24 |
make -fwin32.mak DerelictSDL DC=DMD |
|---|
| 25 |
</code></pre> |
|---|
| 26 |
For more information on compiling Derelict libraries, see <a href="build.html">Building the |
|---|
| 27 |
Derelict Bindings</a>. |
|---|
| 28 |
|
|---|
| 29 |
<h3>Using</h3> |
|---|
| 30 |
<ol> |
|---|
| 31 |
<li>Always make sure the DerelictSDL source modules are available on your import |
|---|
| 32 |
path.</li> |
|---|
| 33 |
<li>In modules that make use of DerelictSDL, you will need to import the |
|---|
| 34 |
<tt>derelict.sdl.sdl</tt> module.</li> |
|---|
| 35 |
<li>You must link your application with the DerelictSDL and DerelictUtil libraries.</li> |
|---|
| 36 |
<li>Before calling any SDL functions, you need to make a call to <tt>DerelictSDL.load()</tt>. |
|---|
| 37 |
This will load the shared library.</li> |
|---|
| 38 |
</ol> |
|---|
| 39 |
|
|---|
| 40 |
<p> |
|---|
| 41 |
The following is a complete program that loads DerelictSDL: |
|---|
| 42 |
</p> |
|---|
| 43 |
|
|---|
| 44 |
<pre> |
|---|
| 45 |
import derelict.sdl.sdl; |
|---|
| 46 |
|
|---|
| 47 |
void main() |
|---|
| 48 |
{ |
|---|
| 49 |
DerelictSDL.load(); |
|---|
| 50 |
|
|---|
| 51 |
// now you can call SDL functions |
|---|
| 52 |
} |
|---|
| 53 |
</pre> |
|---|
| 54 |
<p> |
|---|
| 55 |
As with other Derelict bindings, DerelictSDL will throw an exception if an error |
|---|
| 56 |
occurs while loading the shared library. For more information on Derelict |
|---|
| 57 |
exceptions, see the documentation for |
|---|
| 58 |
<a href="use.html#Exceptions">Using the Derelict Bindings</a>. |
|---|
| 59 |
</p><p> |
|---|
| 60 |
Finally, the method <tt>DerelictSDL.unload()</tt> is provided for convenience. In normal |
|---|
| 61 |
practice you do not need to call this function, as Derelict will unload the library |
|---|
| 62 |
automatically when the app exits. You generally should only use this function if |
|---|
| 63 |
you need to unload DerelictSDL while the application is running or if you disable the |
|---|
| 64 |
automatic unloading of shared libraries (as per <a href="util.html#Loader">the documentation for the loader module</a>). |
|---|
| 65 |
</p> |
|---|
| 66 |
|
|---|
| 67 |
<h3>Things You Need To Know</h3> |
|---|
| 68 |
<ul> |
|---|
| 69 |
<li><tt>SDL_VideoInfo</tt> is defined differently in DerelictSDL than it is in SDL. This is because |
|---|
| 70 |
the C version makes use of bitfields, which D does not support. Currently, DerelictSDL |
|---|
| 71 |
replaces all bitfields in the structure definition with a single <tt>uint</tt> field called |
|---|
| 72 |
<tt>flags</tt>. It is still possible to access the individual bitfield flags by using bit |
|---|
| 73 |
manipulation operators, but unless you know what you are doing it is recommended that you |
|---|
| 74 |
not do so. Instances of SDL_VideoInfo are created on the C side, not in D. There is |
|---|
| 75 |
nothing in the C standard which specifies the order of the bits in the bitfield |
|---|
| 76 |
(i.e. the first field encountered might become the low order or high order bit), |
|---|
| 77 |
so what may work with one SDL shared library on one platform might not work with an |
|---|
| 78 |
SDL shared library on another platform (or even on the same platform if compiled |
|---|
| 79 |
with a different compiler). So please keep in mind that manipulating the <tt>flags</tt> |
|---|
| 80 |
field of DerelictSDL's SDL_VideoInfo could result in unexpected consequences.</li> |
|---|
| 81 |
</ul> |
|---|
| 82 |
</body> |
|---|
| 83 |
</html> |
|---|
