Changeset 255

Show
Ignore:
Timestamp:
04/21/07 07:56:54 (1 year ago)
Author:
aldacron
Message:

[Docs]
* corrected several spelling mistakes
* tweaked the wording of a few passages to make for clarity or to just make them more proper
* fixed a couple of glaring bugs that caused some bits of text to be invisible
* deleted a some things that were no longer relevant

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/docs/ft.html

    r158 r255  
    2222Windows users. All users should be sure to read the accompnaying NOTES.txt 
    2323in the DerelictFT directory for more information.</div> 
    24  
    25 <div class="important">Currently, there is a bug with DMD that prevents 
    26 DerelictFT from compiling when the -debug switch is specified. Because of this, 
    27 the package's forbuild.txt cancels -debug when present. If you build the package 
    28 yourself, without using the Derelict build script, keep that in mind.</div> 
    2924 
    3025<h3>Using</h3> 

  • trunk/docs/gl.html

    r233 r255  
    11<html lang="en"> 
    22<head> 
    3    <title>DerelictGL</title> 
    4    <link rel="stylesheet" type="text/css" href="styles.css"> 
     3    <title>DerelictGL</title> 
     4    <link rel="stylesheet" type="text/css" href="styles.css"> 
    55</head> 
    66<body> 
    …… 
    3535void main() 
    3636{ 
    37    DerelictGL.load(); 
    38      
    39    // now you can call OpenGL functions 
     37    DerelictGL.load(); 
     38 
     39    // now you can call OpenGL functions 
    4040} 
    4141</pre> 
    4242 
    4343<div class="note">Return values and parameters of type <tt>GLubyte*</tt>, when 
    44 instended to represent a string, have been declared in DerelictGL as <tt>char*</tt>  
     44intended to represent a string, have been declared in DerelictGL as <tt>char*</tt> 
    4545instead.</div> 
    4646 
    4747<p> 
    4848As with other Derelict packages, DerelictGL will throw an exception if an error 
    49 occurs while loading the shared library. For more information on Derelict  
     49occurs while loading the shared library. For more information on Derelict 
    5050exceptions, see the documentation for 
    5151<a href="loading.html">Loading/Unloading Shared Libraries</a>. 
    …… 
    6464an OpenGL application for general public consumption, there is no way to guarantee 
    6565which version of the API will be available on any user's system until the 
    66 application is actually run on that system.  
     66application is actually run on that system. 
    6767</p><p> 
    6868Another issue is presented by 
    …… 
    7171on Windows 95. Furthermore, this DLL is a (rather poor) software implementation. Vista 
    7272ships with the software implementation, but also includes an OpenGL DLL that supports 
    73 up to core OpenGL 1.4 and is implemented on top of D3D. This DLL provides hardware 
     73up to core OpenGL 1.4 and is implemented on top of Direct3D. This DLL provides hardware 
    7474acceleration, but all of the calls first go through a translation layer to convert 
    7575them to D3D calls. The system can load the implementation provided by the 
    …… 
    102102<tt>void DerelictGL.loadVersions(GLVersion minVersion)</tt><br /> 
    103103This method will attempt to load a specific verision of OpenGL. If any version 
    104 of OpenGL up to and including the version requested fails to load successfully,  
     104of OpenGL up to and including the version requested fails to load successfully, 
    105105then this method throws a <span class="bold">SharedLibProcLoadException</span>. 
    106106</p> 
    …… 
    108108Before attempting to load any functions, two checks are made. The first check is 
    109109to determine if an OpenGL context has been made current. If not, this method 
    110 will throw an <span class="bold">Error</span>. The method next determines 
     110will throw an <span class="bold">Exception/span>. The method next determines 
    111111if a check has been made internally for the latest available version supported 
    112112by the driver. If not, that check is made. Only then are the functions loaded. 
    113113</p><p> 
    114 When this function returns successfully, a call to  
     114When this function returns successfully, a call to 
    115115<span class="bold">DerelictGL.availableVersion</span> will return either a value 
    116116greater than or equal to the version you requested to load. If an exception is 
    …… 
    121121<p> 
    122122<tt>GLVersion DerelictGL.availableVersion()</tt><br /> 
    123 When this method is called, it first checks to determine if the availabel 
     123When this method is called, it first checks to determine if the available 
    124124version has already been set. If not, it will query the driver for the highest 
    125125version supported and <span class="bold">then will attempt to load each supported 
    126126version</span>. A successful load will result in a return value that indicates 
    127127the highest loaded version. A failure will result in an 
    128 <span class="bold">Error</span> if no context is current, or a 
     128<span class="bold">Exception</span> if no context is current, or a 
    129129<span class="bold">SharedLibProcLoadException</span> if any function failed to 
    130130load. Successive calls will always return the latest loaded version as long 
    …… 
    134134<p> 
    135135<tt>char[] DerelictGL.versionString(GLVersion glv)</tt><br /> 
    136 Returns the string form of the given version. The format of the string is "Version X.X".  
     136Returns the string form of the given version. The format of the string is "Version X.X". 
    137137</p> 
    138138 
    …… 
    140140<tt>bool DerelictGL.hasValidContext()</tt><br /> 
    141141Returns true if a context has been made current. This is used internally before 
    142 attempting any loads that require an active context, but is also publicly  
     142attempting any loads that require an active context, but is also publicly 
    143143available. You may find this useful if you have an application that manages 
    144144multiple OpenGL contexts. 
    …… 
    153153</p> 
    154154<pre> 
     155// Example 1: Requesting a specific version. 
    155156import derelict.opengl.gl; 
    156157import derelict.util.exception; 
    …… 
    158159void main() 
    159160{ 
    160     // load OpenGL 1.1 
    161     DerelictGL.load(); 
    162      
    163     // attempt to load every version up to OpenGL 1.5 
    164     try 
    165     { 
    166     } 
    167     catch(SharedLibProcLoadException slple) 
    168     { 
    169         // here, you can check the highest version actually loaded. It is possible 
    170         // that a version higher than 1.5 caused the exception, in which case 
    171         // you might choose to continue. If available version is actually 
    172         // lower than 1.5, you should decide what to do bases on your 
    173         // application requirements (i.e. if you absolutely require 1.5, abort, 
    174         // but if not, you might fall back on extensions). Then again, an exception 
    175         // may likely indicate a big problem with the shared library, in which 
    176         // case aborting may be the best option no matter what 
    177          
    178         /* Do Something Here */ 
    179     } 
    180      
    181     // at this point, you might be satisfied knowing that you have 1.5 available, 
    182     // or you might want to see if later versions are available 
    183     GLVersion glv = DerelictGL.availableVersion(); 
    184     if(glv > 1.5) 
    185     { 
    186         /* Do Something Here */ 
    187     } 
     161    // load OpenGL 1.1 
     162    DerelictGL.load(); 
     163 
     164    // attempt to load every version up to OpenGL 1.5 
     165    try 
     166    { 
     167        DerelictGL.loadVersions(GLVersion.Version15); 
     168    } 
     169    catch(SharedLibProcLoadException slple) 
     170    { 
     171        // Here, you can check which is the highest version that actually loaded. 
     172 
     173        /* Do Something Here */ 
     174    } 
    188175} 
    189176</pre> 
    190177 
    191178<pre> 
     179// Example 2: Loading the highest available version. 
    192180import derelict.opengl.gl; 
    193181import derelict.util.exception; 
    …… 
    195183void main() 
    196184{ 
    197    // load OpenGL 1.1 
    198    DerelictGL.load(); 
    199      
    200    // attempt to load the higest GL version supported by the driver 
    201    GLVersion glv; 
    202    try 
    203    { 
    204        glv = DerelictGL.getAvailableVersion(); 
    205     }  
    206    catch(SharedLibProcLoadException slple) 
    207    { 
    208        // You might want to abort here if you are worried about a corrupt 
    209        // shared library. Otherwise, you'll want to determine what was 
    210        // actually loaded. 
    211        glv = DerelictGL.getAvailableVersion(); 
    212    } 
    213      
    214    switch(glv) 
    215    { 
    216        ... 
    217    } 
    218      
     185    // load OpenGL 1.1 
     186    DerelictGL.load(); 
     187 
     188    // attempt to load the higest GL version supported by the driver 
     189    GLVersion glv; 
     190    try 
     191    { 
     192        glv = DerelictGL.getAvailableVersion(); 
     193    } 
     194    catch(SharedLibProcLoadException slple) 
     195    { 
     196        // You might want to abort here if you are worried about a corrupt 
     197        // shared library. Otherwise, you'll want to determine what was 
     198        // actually loaded. 
     199        glv = DerelictGL.getAvailableVersion(); 
     200    } 
     201 
     202    switch(glv) 
     203    { 
     204        ... 
     205    } 
     206 
    219207} 
    220208</pre> 
    …… 
    222210<div class="note"> 
    223211It should be noted that Derelict's <a href="selective.html">selective loading 
    224 mechanism</a> may be used to bypass exceptions in loading versions later than 
    225 1.2. However, it is not recommended you do so unless there is a very compelling 
     212mechanism</a> may be used when loading versions later than 1.2. However, it is 
     213not recommended you do so unless there is a very compelling 
    226214reason. 
    227215</div> 

  • trunk/docs/sdl.html

    r157 r255  
    2222in DerelictSDL than it is in SDL. This is because the C version makes use of 
    2323bitfields, which D does not support. Currently, DerelictSDL replaces all bitfields 
    24 in the structure definition with a single uint field called  <tt>flags</tt>. It is 
     24in the structure definition with a single <tt>uint</tt> field called  <tt>flags</tt>. It is 
    2525still possible to access the individual bitfield flags by using bit manipulation 
    2626operators, but unless you know what you are doing it is recommended that you not 

  • trunk/docs/sdlimg.html

    r149 r255  
    4848<a href="loading.html">Loading/Unloading Shared Libraries</a>. 
    4949</p> 
    50 <div class="note">In any module calls SDL_image functions, you will also need 
     50<div class="note">In any module that calls SDL_image functions, you will also need 
    5151to import derelict.sdl.sdl. This is not required to load the library, as shown 
    5252above.</div> 

  • trunk/docs/sdlmix.html

    r149 r255  
    4949</p> 
    5050<div class="note"> 
    51 In any module where you wish to call SDL_mixer functions, you will also need 
     51In any module that calls SDL_mixer functions, you will also need 
    5252to import derelict.sdl.sdl. This is not required to load the library, as shown 
    5353above.</div> 

  • trunk/docs/sdlnet.html

    r149 r255  
    4747<a href="loading.html">Loading/Unloading Shared Libraries</a>. 
    4848</p> 
    49 <div class="note">In any module where you wish to call SDL_net functions, you will also need 
     49<div class="note">In any module that calls SDL_net functions, you will also need 
    5050to import derelict.sdl.sdl. This is not required to load the library, as shown 
    5151above.</div> 

  • trunk/docs/sdlttf.html

    r149 r255  
    4747<a href="loading.html">Loading/Unloading Shared Libraries</a>. 
    4848</p> 
    49 <div class="note">In any module where you wish to call SDL_ttf functions, you will also need 
     49<div class="note">In any module that calls SDL_ttf functions, you will also need 
    5050to import derelict.sdl.sdl. This is not required to load the library, as shown 
    5151above.</div> 

  • trunk/docs/styles.css

    r254 r255  
    7777    font-weight: bold; 
    7878    color: #FF0000; 
     79    margin-top: .5em; 
     80    margin-bottom: .5em; 
    7981} 
    8082 

  • trunk/docs/util.html

    r165 r255  
    1111<hr> 
    1212<h3>Introduction</h3> 
    13 DerelictUtil currently provides two modules: <tt>derelict.util.exception</tt> and 
    14 <tt>derelict.util.loader</tt>. The former provides optional functionality that 
    15 the client can use to make an application as robust as possible, while the latter 
    16 is intended primarily for internal use by the Derelict packages. Regardless of 
    17 whether or not the client imports any modules from DerelictUtil, the other 
    18 Derelict packages all have an implicit dependency upon DerelictUtil. As such, when 
    19 building an application that uses Derelict, the DerelictUtil library must be linked 
    20 to the application. 
     13DerelictUtil contains four modules. Of these, two are intended exlusively for 
     14internal use. Of the other two, one, <tt>derelict.util.exception</tt>, provides 
     15optional functionality that the client can use to make an application as robust 
     16as possible. The other, <tt>derelict.util.loader</tt> is primarily intended for 
     17internal use but may be useful for anyone needing to manually load a shared 
     18library in their application. Regardless of whether or not the client imports 
     19any modules from DerelictUtil, the other Derelict packages all have an implicit 
     20dependency upon DerelictUtil. As such, when building an application that uses 
     21Derelict, the DerelictUtil library must be linked to the application. 
    2122 
    2223<h3>The Exception Module</h3> 
    …… 
    2425you must import <tt>derelict.util.exception</tt>. It defines three exception types 
    2526that can be thrown when a shared library fails to load, and also defines the 
    26 interface for <a href="selective.html">selective symbol exceptions</a>. 
     27interface for <a href="selective.html">selective symbol loading</a>. 
    2728 
    2829<p><hr></p><p> 
    …… 
    3334that matches the name returned by the <tt>sharedLibName</tt> property of this 
    3435exception.</p> 
    35   
     36 
    3637<p><tt>SharedLibProcLoadException</tt><br> 
    3738This exception is thrown when a symbol cannot be loaded from a shared library. 
    3839This might indicate that the library is corrupt, or that it is a different version 
    39 than what was expected. In other words, the library exists on the system, but 
     40than expected. In other words, the library exists on the system, but 
    4041no symbol that matches the name returned by the <tt>procName</tt> property of 
    4142this exception could be found. In some cases, it may be desirable to prevent this 
    42 exception from being thrown. You can learn how by reading about  
    43 <a href="selective.html">Selective Symbol Exceptions</a>.</p> 
     43exception from being thrown. You can learn how by reading about 
     44<a href="selective.html">Selective Symbol Loading</a>.</p> 
    4445 
    4546<p><tt>InvalidSharedLibHandleException</tt><br> 
    …… 
    5253This function allows the client to set a callback that will be called when a 
    5354symbol cannot be found in a shared library. The name of the library will be passed 
    54 to the callback in the <tt>libName</tt> parameter, and the name of the missing  
    55 symbol is in the <tt>procName</tt> parameter. The client can use these parameters  
     55to the callback in the <tt>libName</tt> parameter and the name of the missing 
     56symbol in the <tt>procName</tt> parameter. The client can use these parameters 
    5657to determine if Derelict should continue loading the shared library. If so, then 
    5758the callback should return true. If Derelict should abort loading and throw an exception, 
    5859the callback should return false. Note that the callback must be set before loading 
    5960the library(ies) you are interested in. You can read more about this feature in 
    60 the <a href="selective.html">Selective Symbol Exceptions</a> documentation.</p> 
     61the <a href="selective.html">Selective Symbol Loading</a> documentation.</p> 
    6162<p><hr></p> 
    6263 
    …… 
    6465<tt>derelict.util.loader</tt> provides a common interface for Derelict packages 
    6566to load shared libraries. You should generally only use this module if you are 
    66 creating a new package for inclusion in Derelict. However, it DerelictUtil can 
    67 be used as a standalone package if you so desire, perhaps as a replacement for 
     67creating a new package for inclusion in Derelict. However, it is useful if you 
     68need to load other shared libraries in your Derelict application. Also, 
     69DerelictUtil can be used as a standalone package, perhaps as a replacement for 
    6870<tt>std.loader</tt>. 
    6971 
    7072<p><hr></p><p> 
    7173<tt>SharedLib Derelict_LoadSharedLib(char[] libName)</tt><br> 
    72 Opens a handle to a shared library, and returns a reference handle of type 
    73 <tt>SharedLib</tt>. This handle is used by other functions in this module to 
    74 manipulate the shared library. If the library cannot be loaded for some reason, 
    75 a <tt>SharedLibLoadException</tt> is thrown.</p> 
     74Opens and returns a shared library handle of type <tt>SharedLib</tt>. This handle 
     75is used by other functions in this module to manipulate the shared library. If  
     76the library cannot be loaded, a <tt>SharedLibLoadException</tt> is thrown.</p> 
    7677 
    77 <p><tt>>SharedLib Derelict_LoadSharedLib(char[][] libNames)</tt><br> 
     78<p><tt>SharedLib Derelict_LoadSharedLib(char[][] libNames)</tt><br> 
    7879Given an array of shared library names, returns a handle to the first shared 
    7980library successfully loaded. This is intended for use on platforms where a single 
    …… 
    8283load, an exception is thrown for the last library name.</p> 
    8384 
    84 <p><tt><void* Derelict_GetProc(SharedLib lib, char[] procName)</tt><br> 
     85<p><tt>void* Derelict_GetProc(SharedLib lib, char[] procName)</tt><br> 
    8586Given a handle to a shared library and the name of a symbol, this function loads 
    8687the symbol from the shared library into memory and returns a pointer to it. This 
    …… 
    8889the symbol cannot be found, this function first checks if a <tt>MissingProcCallback</tt> 
    8990has been set and, if so, calls it. Otherwise a <tt>SharedLibProcLoadException</tt> 
    90 is thrown. If the shared library referenced by the handle has already been  
     91is thrown. If the shared library referenced by the handle has already been 
    9192unloaded, an <tt>InvalidSharedLibHandleException</tt> is thrown.</p> 
    9293 
    …… 
    9495Unloads a shared library from memory. The library handle will no longer be valid. 
    9596Attempts to use it again could cause an <tt>InvalidSharedLibHandleException</tt> to 
    96 be thrown. However, if an invalid shared library handle is passes to this function, 
     97be thrown. However, if an invalid shared library handle is passed to this function, 
    9798no exception is thrown and the function is a no-op. 
    9899</body> 

  • trunk/docs/vorbis.html

    r157 r255  
    1212<h3>Introduction</h3> 
    1313<p>DerelictVorbis is a D binding to Xiph.org's <a href="http://www.xiph.org/vorbis"> 
    14 Ogg Vorbis codec</a>.&nbsp; Vorbis is a compresed audio format similar to mp3, but 
     14Ogg Vorbis codec</a>.&nbsp; Vorbis is a compressed audio format similar to mp3, but 
    1515allows smaller filesizes with the same level of audio quality and is also 
    1616patent-free and open source.</p>