+ Once Allegro 4.2 is released, we plan to maintain backward compatibility
+ at the Application Binary Interface level for the subsequent releases of
+ the 4.2.x series. For example, that means you will be able to use an
+ executable compiled using version 4.2.0 with version 4.2.5 or 4.2.41 of
+ the dynamically linked library.
+
+
+ However, there are some guidelines (rules) you should (must) follow,
+ otherwise things will not work, and you will get angry emails from
+ users and from us.
+
+
+ Note: ABI compatibility will only be _actively_ maintained for:
+
+
Windows on x86
+
Linux on x86
+
Linux on x86-64
+
MacOS X on PowerPC
+
+
+
+ We will not be maintaining "forwards compatibility", meaning that
+ programs compiled with a newer release of Allegro may not necessarily
+ run on a target system which has an older release of Allegro installed.
+ You would have to upgrade the Allegro DLL on the target system. While
+ we will try to minimise these kinds of forced upgrades, it should give
+ us more flexibility within the stable series.
+
+
+
+
+ If you don't need a modified version of Allegro then just link your
+ program against an officially blessed non-WIP, non-CVS, non-dodgy
+ version. Don't disable any features (eg. colour depths, drivers) in
+ the DLL.
+
+
+ If you require a modified version of Allegro, then please either
+ statically link, or pick a non-standard name for the Allegro DLL.
+ For example, don't distribute a modified version of Allegro under a
+ name such as all42.dll or alleg42.dll. Instead, call it something
+ like alcustom.dll. Even better, statically link.
+
+
+ For the people who use vanilla Allegro, we will provide a set of
+ "reference" DLLs. If your binary works with those then everything is
+ fine. If you want to distribute Allegro DLLs with your program
+ (usually a good idea), we recommend you distribute our DLLs instead
+ of ones you compiled yourself.
+
+
+
+
+ To make sure an Allegro binary compiled on your machine will work on
+ another machine, do not disable any "features" with `configure'. Your
+ copy of Allegro must have assembly routines, threads, modules, all
+ colour depths and X11 support enabled, amongst other things. If in
+ doubt, leave it at the default setting.
+
+
+ When you are ready to distribute your binary, run "ldd <mybinary>".
+ It should say something like:
+
+
+ If you see the latter, that would mean users with later versions of
+ Allegro would not be able to run your binary.
+
+
+ See also the Windows section if you need to use a modified version of
+ Allegro.
+
+
+ For people packaging Allegro for redistribution: Drivers that are
+ built as dynamically loaded modules may be disabled or left out, but
+ all others should be left in. Examples of drivers that are _not_
+ dynamically loaded include: OSS digital sound and OSS MIDI. In
+ short, if a program built against a copy of default-options Allegro
+ will work with your final library it should be fine.
+
+
+
+
+ The situation is basically the same as for Linux on x86, however
+ your copy of Allegro must NOT have assembly routines enabled (it
+ wouldn't work anyhow).
+
+
+
+
+ On OSX there are two 'styles' of linking - Unix style and Mac style.
+ For the Unix style linking, you would use `allegro-config --libs`
+ on the link line. For versioning, follow the advice given in the
+ 'Linux on x86' section above, using the command otool -L instead
+ of ldd.
+
+
+ For example, otool -L <mybinary> should give
+
+
+ liballeg-4.2.dylib (compatibility version 4.2.0, current version 4.2.0)
+
+
+ For the Mac style, use `allegro-config --frameworks` on the link
+ line, or add Allegro.framework to your project if you are using
+ XCode. In this case, the versioning is done inside the framework
+ itself.
+
+
+ Apple recommends that an application should be entirely self-
+ contained. To achieve this in Allegro, static-link the executable
+ and use fixbundle to bind all its resources together. In this
+ way, you will not need to worry about incompatible versions of
+ the library. This is useful if you are distributing an application.
+
+
+ There is a known compatibility problem when using gcc 4 on MacOS X 10.4
+ that prevents binaries from working on older versions of MacOS X. While it
+ is anticipated that a future update from Apple will fix this problem, you
+ can use gcc 3 to work around it.
+
+
+
+
+ Providing source is still better than not providing source. Binaries
+ are good, however, if your code sucks and only you (with the help of
+ witchcraft) can compile it.
+
+
+ If you provided binaries in the past using WIP versions of Allegro,
+ we politely request that you recompile your program using a stable
+ version of Allegro.
+
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/ahack.html b/lib/allegro/allegro-htmldocs-4.2.1/ahack.html
new file mode 100644
index 0000000..f2e2e67
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/ahack.html
@@ -0,0 +1,668 @@
+
+
+Allegro Hacker's Guide
+
+
+
+
+
+The Allegro Hacker's Guide
+
+
+
+This is a guide to some of the internal workings of Allegro, for people who
+are interested in hacking on it. This document is far from complete, and may
+not always be 100% accurate. Remember that when in doubt, the sources are
+always the definitive reference. Suggestions for what to include in this
+document will be very welcome: there is far too much code for me to go over
+it all in any kind of detail, so I want to concentrate on the things that
+people find most confusing...
+
+
+
+
+I'm not going to be a fascist about this, but it does make life easier if
+all the code uses a consistent layout. If you are going to write and
+maintain more than one complete source file of your own, I think you are
+entitled to do that however you like, but for smaller contributions, I will
+probably reformat your code to fit in with my existing style. It will
+obviously save me time if you write it this way in the first place, hence
+this description:
+
+
+Basic Allegro style: K&R, with 3 space indentation. On disk, though, tab stops
+are 8 spaces, so if for example a line was indented by 12 spaces, this would be
+saved out as either 12 space characters or 1 tab and 4 spaces, not as 4 tabs.
+Because this format always will lead to code display looking broken in place or
+another, new patches should now always use spaces only and no longer contain
+tabs. The indent.pro file included with the Allegro distribution comes close to
+getting this layout right, but doesn't quite manage it, so some things still
+need to be cleaned up by hand.
+
+
+Preprocessor defines and structure names are UPPER_CASE. Function and
+variable names are lower_case. MixedCaseNames are evil and should not be
+used. That silly m_pHungarian notation is _really_ evil and should not even
+be thought about.
+
+
+All symbols should be declared as static unless that is absolutely not
+possible, in which case they should be prefixed with an underscore.
+
+
+Functions look like this:
+
+/* foobar:
+ * Description of what it does.
+ */
+void foobar(int foo, int bar)
+{
+ /* do some stuff */
+}
+
+Author credits should be added in chronological order, and email addresses
+should not be included: those can be found in the main credits file, and if
+they only exist in one place, it is easier to update them when people change
+address.
+
+
+People only need to be listed in the source file header if they've made a
+significant contribution to it (one-line fixes don't count), but no matter
+how small their addition, they must be added to the docs/thanks._tx file.
+This is sorted alphabetically by name. If they are already in it, update the
+text to describe the new addition, otherwise make a new entry for the new
+contributor. Also, anything more than very tiny modifications should be
+added to the docs/changes._tx file, which grows from the top in reverse
+chronological order. This file should briefly describe both the nature of
+the modification and who did it.
+
+
+
+
+This is very different depending on whether you are using autoconf or a
+fixed makefile. For most platforms, though, the fixup script (eg.
+fixdjgpp.bat), will create a small makefile, which defines MAKEFILE_INC to
+the make of another file (eg. makefile.dj), and then includes makefile.all.
+This contains a lot of generic rules, and includes the file named in
+MAKEFILE_INC to provide additional platform-specific information. The actual
+source files are listed in makefile.lst.
+
+
+There are three library targets: alleg (release), alld (debugging), and allp
+(profiling). Objects go in obj/compiler/version/, where version is one of
+alleg, alld, or allp. Libraries go in lib/compiler/. A few generated things
+(asmdefs.inc, mmxtest.s, etc), go in the root of obj/compiler/. Dependencies
+are generated by "make depend", and go in obj/compiler/version/makefile.dep,
+which is included by makefile.all.
+
+
+When you run "make clean", this only deletes harmless generated files like
+the objects. "make distclean" strips you right back to the original
+distribution, including getting rid of the test executables and the library
+itself. For the ultimate in personal hygene, run "make veryclean", which
+will wipe absolutely all generated files. After doing this, you will have to
+run "make depend" before you can build the library, and also "fixdll.bat" if
+you are working on a Windows platform.
+
+
+To pass long commandlines to the MSVC and Watcom linkers, the program
+runner.exe is compiled using gcc, so make can pass it a decent number of
+arguments. This just saves the parameters into a temporary file, and then
+invokes the real command using that as an argument file.
+
+
+All the makefiles currently use gcc for dependency generation, because this
+is easier than trying to get MSVC or Watcom to output the right info.
+
+
+The symbol LIBRARY_VERSION, defined at the top of the makefile.ver, is used
+for including a version number in things like the DLL filename.
+
+
+
+
+allegro.h lives in the include/ directory. It is only a placeholder which
+includes other headers which live in the include/allegro/ tree. The reason
+for this slightly odd approach is that allegro.h can include things like
+"allegro/keyboard.h", which will work both in-situ within the build
+directory, and if we copy allegro.h to the system include directory and the
+other headers into system_include/allegro/. This avoids cluttering the
+system directories with lots of our headers, while still allowing programs
+to just #include <allegro.h>, and also makes it possible for people to
+access keyboard stuff with #include <allegro/keyboard.h>.
+
+
+base.h includes alconfig.h, which checks the current platform and includes
+a helper header for this compiler (aldjgpp.h, almsvc.h, alwatcom.h, etc).
+That helper header defines a bunch of macros describing the system, emulates
+whatever things are needed to make the code compile properly, and optionally
+defines ALLEGRO_EXTRA_HEADER and ALLEGRO_INTERNAL_HEADER if it is going to
+need any other platform-specific includes.
+
+
+After including the platform header, the rest of alconfig.h defines a lot of
+generic helper macros to their default values, but only if the platform
+header hasn't already overridden these to something specific.
+
+
+Every module-specific header contains structure definitions and function
+prototypes. At the end of the file, it may include a header from the
+include/allegro/inline/ directory which defines related inline routines.
+If inline asm is supported, this can include in turn asm.inl which imports
+routines from one of the compiler-specific files al386gcc.h, al386vc.h and
+al386wat.h; otherwise C versions are used instead. The header alinline.h
+is a placeholder which includes all the headers defining inline functions.
+
+
+If ALLEGRO_EXTRA_HEADER is defined, allegro.h includes this at the very end.
+This is used to include one of the files aldos.h, alwin.h, etc, which define
+platform-specific things like ID values for the hardware drivers. Unlike the
+platform files included from the top of allegro.h, these are specific per-OS
+rather than per-compiler, so the same alwin.h can be used by both MSVC and
+MinGW. They describe library functions that relate to this platform, while
+the earlier header described the basic language syntax.
+
+
+aintern.h is like the internal.h in earlier Allegro versions, defining
+routines that are shared between multiple sources, but that we don't
+generally want user programs to see.
+
+
+On platforms which have specific, non-portable API routines of their own,
+these should go in a special header in the root of the include directory,
+eg. winalleg.h. This can be included by user programs that want to access
+these routines, while making it very clear to them that by including this
+header, they are writing non-portable code.
+
+
+
+
+All header function prototypes should use the macro AL_FUNC(). Inline
+routines use the macro AL_INLINE(). Global variables use AL_VAR() or
+AL_ARRAY(). Global pointers to functions use AL_FUNCPTR(). Pointers to
+functions which are passed as parameters to other routines or stored in a
+structure typedef use AL_METHOD(). This may seem like something of an
+overkill, but it gives us a lot of flexibility to add DLL import/export
+specifiers, calling convention markers like __cdecl, and even to mangle
+symbol names on some compilers. If you forget to use these macros, your code
+won't work on some platforms.
+
+
+This only applies to header files, though: you can write normal code in the
+C sources.
+
+
+The symbol ALLEGRO_SRC is defined while compiling library source files. If
+you want to inline a function in one of your sources, use the INLINE macro.
+To declare a zero-sized array in terminal position inside a structure, use
+the ZERO_SIZE_ARRAY(type, name) macro. To use 64 bit integers, declare a
+LONG_LONG variable (this won't be defined on all platforms). To do things
+with filenames, check the macros ALLEGRO_LFN, OTHER_PATH_SEPARATOR, and
+DEVICE_SEPARATOR. See the headers for details.
+
+
+
+
+Do not assume that strings are ASCII. They aren't. If you assume they are,
+your code might work for a while as long as people are only using it with
+UTF-8 data, but it will die horribly as soon as someone tries to run it with
+16 bit Unicode strings, or Chinese GB-code, or some strange MIME format,
+etc. Whenever you see a char * being passed around, you must be aware that
+this will actually contain text in whatever format is currently selected, so
+you have to be damn careful when manipulating strings. Don't ever forget and
+call a regular libc routine on them!
+
+
+Use the Unicode functions for all your text manipulation: see the docs for
+details. When allocating a scratch string on the stack, assume that each
+character will occupy at most four bytes: this will give you more than
+enough space for any of the current encoding schemes.
+
+
+If you want to specify a constant string, use the function
+uconvert_ascii("my string", buf) to obtain a copy of "my string" in the
+current encoding format. If buf is NULL, this will use an internal static
+buffer, but the converted string will be overwritten by the next call to any
+format conversion routines, so you shouldn't pass it down into other library
+functions. Normally you should provide the conversion space yourself,
+allocating buf as a temporary object on the stack.
+
+
+To convert the other way (eg. before passing an Allegro string to an OS
+routine that expects ASCII data), call uconvert_toascii(mystring, buf).
+
+
+For any messages that may be seen by the user, you can call
+get_config_text("my ascii string") instead of uconvert_ascii(). This will
+return a pointer to persistent memory (so it is ok to keep the string around
+indefinitely), after converting into the current text encoding format. This
+function is cool because it saves you having to bother allocating space for
+the converted data, and because it allows the string to be replaced by the
+translations in language.dat. You should be sure to always pass a constant
+string to get_config_text(), rather than any generated text or data from
+other string variables: this is so that the findtext.sh script can easily
+locate all the strings that need to be translated.
+
+
+Hardware drivers should initialise their name and desc fields to the global
+empty_string, and store an ASCII driver name in their ascii_name field. The
+framework code will automatically translate and convert this value, storing
+the result in both the name and desc fields. For most drivers this will be
+enough, but if you want to provide a more detailed description, it is up to
+your driver to set this up from their init routine, and take care of all the
+required conversions.
+
+
+
+
+Structure offsets are defined in asmdef.inc, which is generated by asmdef.c.
+This allows the asm code to use human readable names for the structure
+members, and to automatically adjust whenever new fields are added, so it
+will always exactly match the layout of the C structures.
+
+
+Asm code should use the macro FUNC(name) to declare the start of a routine,
+and GLOBL(name) whenever it wants to refer to an external symbol (eg. a C
+variable or function). This is to handle name mangling in a portable way
+(COFF requires an underscore prefix, ELF does not).
+
+
+You can modify %ds and %es from asm, as long as you put them back. If USE_FS
+and FSEG are defined, you can also change %fs, otherwise this is not
+required and you can safely use nearptr access for everything.
+
+
+Don't assume that the MMX opcodes will be supported: not every assembler
+version knows about these. Check the ALLEGRO_MMX macro, and be sure to give
+up gracefully if these instructions are not available.
+
+
+
+
+One of the nicest features of Allegro is its excellent manual, that you can
+read in several formats, ranging from plain text to compiled HTML. All API
+functions of the library have to be documented in docs/src/allegro._tx in the
+appropriate section. Note that, whatever you write in the file, you shouldn't
+exceed a line width of 78 characters, except for lines which contain tags.
+This rule is needed in order to produce correct plain text documentation that
+doesn't extend beyond the standard 80 column screen/terminal. All the other
+formats are less strict about line width and will probably reformat the text
+anyway.
+
+
+If the function you are documenting returns a value, use the @retval command
+to start the chunk of text that describes the return value or how it is used.
+If the function takes parameters, document if they are required to follow a
+specific format (e.g. string encoding), what they are for, and their range of
+values (if any). The latter is particularly important for boolean parameters,
+because there's no way to tell the user that an integer must be either `true'
+or `false' in the C programming language. Parameters are always referred to
+between single quotes, left and right. These are tt-ized in the HTML version,
+but only if there are no space characters between the left and right quote.
+
+
+If it is possible to include a little fragment of code which demonstrates the
+usage of the function, do it just before the @retval command if there is one,
+or at the end of the block. This is very welcome for functions that don't have
+example references (@eref). You don't need to include the declaration of the
+variables unless you really think it can help newbies.
+
+
+Usually a single line will be enough, but don't hesitate to add whatever
+comments you might think of as useful for newbies. Also, if you are writing
+such a one liner, try to use verbose variable names to indicate where they
+come from or what they should contain. Compare the following lines, where the
+second is more likely to be found in `real life' code, but should be avoided
+in these little code fragments taken out of context:
+
+Whatever coding style applies to Allegro's code also applies to these examples
+(e.g. 8 characters tab, 3 spaces indentation). If you are having trouble
+documenting a particular function because you don't know how to approach the
+task (this tends to happen when you have used the function so much that you
+have learnt it by heart), here is a checklist you can follow:
+
+ What is the purpose of the function? Why would the user want to call it?
+
+ Can you call it at any time or is any other function required to have
+ been called before (excluding install_allegro/allegro_init)?
+
+ What do the parameters mean? Do they have a precisely defined type?
+ Do they have a range (like boolean integers)?
+
+ If the function returns a value, what is it? What can it be used for? Is
+ it likely to be the input of another Allegro function? Does the return
+ value have a range (e.g. positive numbers mean success, negative ones
+ failure)?
+
+ Is this function supported across all platforms that Allegro runs on?
+ What does it do if it is not supported? Does it require a more thorough
+ explanation in the platform-specific section of the documentation?
+
+ Should the description say whether the function is reentrant or not?
+ Do you think users would like to use it concurrently in multithreaded
+ environments?
+
+Don't bother about existing example references (@eref). These are generated
+automatically by a script. The person in charge of releasing Allegro will
+most surely do this for you. If you know how to run it, you are very welcome
+to update these tags though, to avoid piling extra work on the maintainer's
+shoulders. Of course, all said about documenting functions applies to macros
+and variables too.
+
+
+
+
+As a developer you are encouraged to spill as many ASSERT and TRACE macros as
+you consider necessary. ASSERT macros are a very good way of enforcing
+documented limitations in input parameters which should never happen during a
+perfect (ie. bugless) version of your game. They are good for things like
+verifying some Allegro subsystem was initialised at the entry point of a
+function which depends on it, or passing NULL pointers where the documentation
+explicitly says the user is not allowed to do so.
+
+
+The TRACE macro is very good for things which are not very repetitive, mainly
+initialisation functions. The problem with C code is that usually error
+reporting to the user programmer layer is done through a simple integer or
+NULL pointer, and the error description (if any) stored in allegro_error. This
+is clearly insufficient for functions like set_gfx_mode() which test many
+graphic drivers before bailing out.
+
+
+What should be the error code in such case? How could you preserve a coherent
+error message to the user in driver A when driver B later overwrites it with
+some other error which may not interest the user trying to run driver A?
+Developers have made plans to include better logging facilities in future
+Allegro releases. In the meantime, it is good if opaque systems like drivers
+use TRACE both to indicate success and failure.
+
+
+For this reason there is a TRACE convention for Allegro code using this macro.
+At the top of the source file you want to use TRACE define three macros:
+PREFIX_I, PREFIX_W, PREFIX_E. Each of this should be a string in the format
+"al-SYSTEM LEVEL: " where SYSTEM is usually the filename creating the TRACE
+(but doesn't have to) and LEVEL is either INFO, WARNING or ERROR respectively.
+Later you can use them like this:
+
+ if (some_error_in_a_deep_obscure_function) {
+ TRACE(PREFIX_E "Couldn't init obscure driver because %s", something);
+ return -1;
+ }
+ TRACE(PREFIX_I "Obscure system initialised with option %s", switch);
+
+Thanks to this prefix convention a user can use the TRACE macro too and grep
+Allegro's messages if there is no interest in them.
+
+
+
+
+Any portable routines that run inside a timer handler or input callback must
+be sure to lock all the code and data that they touch. This is done by
+placing an END_OF_FUNCTION(x) or END_OF_STATIC_FUNCTION(x) after each
+function definition (this is not required if you declare the function as
+INLINE, though), and then calling LOCK_FUNCTION() somewhere in your init
+code. Use LOCK_VARIABLE() to lock global variables, and LOCK_DATA() to lock
+allocated memory.
+
+
+Any modules that have cleanup code should register their exit function by
+calling _add_exit_func(). This will ensure that they are closed down
+gracefully no matter whether the user calls allegro_exit(), falls off the
+bottom of main(), or the program dies suddenly due to a runtime error. You
+must call _remove_exit_func() from inside your shutdown routine, or you will
+find yourself stuck in an endless loop.
+
+
+
+
+Once you are willing to contribute that beautiful hack which does what
+everybody has been waiting for, the fix for that hideous bug which has been
+driving you mad for several nights, the nice improved documentation you would
+have liked to read in the manual for the first time, etc, you have already
+done the hardest part. Now you only need a way to let the Allegro developers
+merge your changes in the main distribution.
+
+
+You could probably send your patch to one of the people working on Allegro,
+but this is not very safe, it depends on the person you chose being available
+and willing to do the work for you. The best you can do is to send your patch
+to the Allegro Developers mailing list. Read the readme.txt file for
+information on how to subscribe to this list. Alternatively, updated
+subscription instructions should always be available at
+http://alleg.sourceforge.net/maillist.html.
+
+
+Sending your patches to the mailing list instead of a single person is good,
+because all the subscribed developers can take a look at your modifications,
+suggest improvements, or find problems, which you can discuss on the same
+mailing list, letting other developers join the conversation when they
+consider appropriate. If the modifications are good, they will probably be
+accepted and merged in the WIP version for the next release. If you aren't
+lucky, or your patch still needs some work, you will be told why it's not
+accepted, or what you have to do to improve it. If you aren't subscribed to
+the list, remember to say this in your message as, by default, replies are
+irected to the list.
+
+
+You can also use SourceForge's issue web trackers, which you can find at
+http://sourceforge.net/tracker/?group_id=5665. This doesn't require you to
+subscribe to any mailing list and you can verify every now and then the
+status of your contribution.
+
+
+
+
+If you have obtained Allegro from an existent release, stable or unstable,
+you will have all the source code contained in some archive format. You will
+need it, because to create a patch you need two versions of each modified
+file, the original version, and your modified version. You will also need
+the diff tool, which is used to create the patches. This tool is usually
+packaged as a standalone package in most GNU/Linux distributions with the
+same name. For DOS, you can get a port from http://www.delorie.com/djgpp/.
+Just choose a mirror from http://www.delorie.com/djgpp/getting.html,
+enter the v2gnu directory and download the difxxb.zip package. While you are
+at it, you can also get a tool named patch (patxxb.zip), which is used to
+apply patches generated by diff, in case you have to apply the patches
+somebody else sends to you. Install the binaries in some directory of your
+path, so that you can use them from anywhere.
+
+
+If you are planing to modify only one file, you will usually copy this file
+to the same name in the same directory with the appended extension '.old'
+before starting to work on it. After you have made your modifications to the
+file, and verified that they please you, go to the directory containing the
+modified and original files and type at the prompt:
+
+ diff -u file.c.old file.c > patch
+
+This command will generate a text file which contains the differences
+between both files in unified output format. Open it with your prefered
+editor and verify that it contains the modifications you wanted to do: lines
+you have added will be marked with a plus sign '+', lines you have removed
+will be marked with a minus sign '-'. If the file is bigger than a few
+kilobytes, compress it before sending to the developers mailing list, and of
+course remember to add an explanation of what the patch is meant to do, why
+it's needed, and any other information you consider relevant.
+
+
+If the modifications you want to do are scattered through several files
+and/or directories, this form of patch generation is very tiresome for both
+ends (you, and the developers). So unpack a fresh copy of the Allegro source
+somewhere and move it to the parent directory where your current version is,
+after giving it another name of course, so as to obtain two complete sources
+trees side by side. Modify the files you wish in your working
+directory. Once you are finished, go back to the parent directory housing the
+two source trees and type:
+
+The '-r' switch makes diff compare directories recursively. Again, do the
+previous steps of verifying your patch, compressing and sending with correct
+instructions. If your patch adds or removes files, you will have to add the
+'-N' switch, because by default diff will ignore files which are only in one
+of the trees. Of course, you might want to run a 'make clean' in your working
+directory before running this command, or you will include lots of generated
+files which have nothing to do with your patch. Or you could edit the
+resulting patch, but that can be error prone.
+
+
+
+
+If you are working with the cvs version of Allegro which you can get from
+Sourceforge (http://sourceforge.net/projects/alleg/), you won't need
+to copy any files at all. Just modify the files you want, go to the root
+directory of the cvs copy and type:
+
+ cvs diff -u > patch
+
+Unlike the standalone diff, the cvs diff command will work recursively
+through the Allegro source tree, comparing each file against the Sourceforge
+repository. The patch will have slightly different headers, but that's ok,
+once you have it follow the previous process to send it to the developers
+mailing list. Of course, check cvs' manual for more information and options.
+
+
+
+
+Sometimes you don't have the diff tool around, or don't have the cvs tool to
+check out the bleeding edge version of Allegro, or you are too lazy to care
+how to actually make the patch yourself. For any of those cases, you can use
+the online Allegro patcher at http://www.allegro.cc/dev/make-diff.php.
+
+
+To use it, first you have to get one of the source files of Allegro and make
+your changes to it. Then, go to that URL and supply the local path on your
+computer to the modified file. Then, you write the path of this file relative
+to Allegro's root. If everything goes well, you will end up with a
+patch you can send to the Allegro developers mailing list or post on
+SourceForge's patch submission page.
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/alleg000.html b/lib/allegro/allegro-htmldocs-4.2.1/alleg000.html
new file mode 100644
index 0000000..263010d
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/alleg000.html
@@ -0,0 +1,577 @@
+
+
set_window_title — Sets the window title of the Allegro program.
+
+
+
+See readme.txt for a general introduction, copyright details, and
+information about how to install Allegro and link your program with it.
+
+
+
int install_allegro(int system_id, int *errno_ptr, int (*atexit_ptr)());
+ Initialises the Allegro library. You must call either this or
+ allegro_init() before doing anything other than using the Unicode
+ routines. If you want to use a text mode other than UTF-8, you can set
+ it with set_uformat() before you call this. The other functions that can
+ be called before this one will be marked explicitly in the documentation,
+ like set_config_file().
+
+
+ The available system ID codes will vary from one platform to another, but
+ you will almost always want to pass SYSTEM_AUTODETECT. Alternatively,
+ SYSTEM_NONE installs a stripped down version of Allegro that won't even
+ try to touch your hardware or do anything platform specific: this can be
+ useful for situations where you only want to manipulate memory bitmaps,
+ such as the text mode datafile tools or the Windows GDI interfacing
+ functions.
+
+
+ The `errno_ptr' and `atexit_ptr' parameters should point to the errno
+ variable and atexit function from your libc: these are required because
+ when Allegro is linked as a DLL, it doesn't have direct access to your
+ local libc data. `atexit_ptr' may be NULL, in which case it is your
+ responsibility to call allegro_exit() manually. Example:
+
Return value:
+ This function returns zero on success and non-zero on failure (e.g. no
+ system driver could be used). Note: in previous versions of Allegro this
+ function would abort on error.
+
+
+
+ Closes down the Allegro system. This includes returning the system to
+ text mode and removing whatever mouse, keyboard, and timer routines have
+ been installed. You don't normally need to bother making an explicit call
+ to this function, because allegro_init() installs it as an atexit()
+ routine so it will be called automatically when your program exits.
+
+
+ Note that after you call this function, other functions like
+ destroy_bitmap() will most likely crash. This is a problem for C++ global
+ destructors, which usually get called after atexit(), so don't put Allegro
+ calls in them. You can write the destructor code in another method which
+ you can manually call before your program exits, avoiding this problem.
+
+
+
+ In order to maintain cross-platform compatibility, you have to put this
+ macro at the very end of your main function. This macro uses some `magic'
+ to mangle your main procedure on platforms that need it like Windows,
+ some flavours of UNIX or MacOS X. On the other platforms this macro
+ compiles to nothing, so you don't have to #ifdef around it. Example:
+
+ int main(void)
+ {
+ allegro_init();
+ /* more stuff goes here */
+ ...
+ return 0;
+ }
+ END_OF_MAIN()
+ Text string used by set_gfx_mode(), install_sound() and other functions to
+ report error messages. If they fail and you want to tell the user why, this
+ is the place to look for a description of the problem. Example:
+
+ Defined to a text string containing all version numbers and maybe some
+ additional text. This could be `4.1.16 (CVS)' for an Allegro version
+ obtained straight from the CVS repository.
+
+
+ This macro can be used to create a packed 32 bit integer from 8 bit
+ characters, on both 32 and 64 bit machines. These can be used for various
+ things, like custom datafile objects or system IDs. Example:
+
+ This macro can be used to check if some Allegro version is (binary)
+ compatible with the current version. It is safe to use > and < to
+ check if one version is more recent than another.
+ The third number is ignored if the second number is even, so
+ MAKE_VERSION(4, 2, 0) is equivalent to MAKE_VERSION(4, 2, 1).
+ This is because of our version numbering policy since 4.0.0:
+ the second number is even for stable releases, which must be
+ ABI-compatible with earlier versions of the same series.
+ This macro is mainly useful for addon packages and libraries. See the
+ `ABI compatibility information' section of the manual for more detailed
+ information. Example:
+
+ The major and minor version of the Operating System currently running.
+ Set by allegro_init(). If Allegro for some reason was not able to
+ retrieve the version of the Operating System, os_version and
+ os_revision will be set to -1. For example: Under Win98 SE (v4.10.2222)
+ os_version will be set to 4 and os_revision to 10.
+
+
+
+ Outputs a message, using a printf() format string. Usually you want to
+ use this to report messages to the user in an OS independant way when some
+ Allegro subsystem cannot be initialised. But you must not use this function
+ if you are in a graphic mode, only before calling set_gfx_mode(), or after
+ a set_gfx_mode(GFX_TEXT). Also, this function depends on a system driver
+ being installed, which means that it won't display the message at all on
+ some platforms if Allegro has not been initialised correctly.
+
+
+ On platforms featuring a windowing system, it will bring up a blocking GUI
+ message box. If there is no windowing system, it will try to print the
+ string to a text console, attempting to work around codepage differences
+ by reducing any accented characters to 7-bit ASCII approximations.
+ Example:
+
+ if (allegro_init() != 0)
+ exit(1);
+
+ if (init_my_data() != 0) {
+ allegro_message("Sorry, missing game data!\n");
+ exit(2);
+ }
+ On platforms that are capable of it, this routine alters the window title
+ for your Allegro program. Note that Allegro cannot set the window title
+ when running in a DOS box under Windows. Example:
+
+ On platforms that have a close button, this routine installs a callback
+ function to handle the close event. In other words, when the user clicks
+ the close button on your program's window or any equivalent device, the
+ function you specify here will be called.
+
+
+ This function should not generally attempt to exit the program or save
+ any data itself. The function could be called at any time, and there is
+ usually a risk of conflict with the main thread of the program. Instead,
+ you should set a flag during this function, and test it on a regular
+ basis in the main loop of the program.
+
+
+ Pass NULL as the `proc' argument to this function to disable the close
+ button functionality, which is the default state.
+
+
+ Note that Allegro cannot intercept the close button of a DOS box in
+ Windows.
+
+
+ Also note that the supplied callback is also called under MacOS X when
+ the user hits Command-Q or selects "Quit" from the application menu.
+ Example:
+
+ Finds out the currently selected desktop color depth. You can use this
+ information to make your program use the same color depth as the desktop,
+ which will likely make it run faster because the graphic driver won't be
+ doing unnecessary color conversions behind your back.
+
+
+ Under some OSes, switching to a full screen graphics mode may automatically
+ change the desktop color depth. You have, therefore, to call this function
+ before setting any graphics mode in order to retrieve the real desktop
+ color depth. Example:
+
+ Finds out the currently selected desktop resolution. You can use this
+ information to avoid creating windows bigger than the current resolution.
+ This is especially important for some windowed drivers which are unable
+ to create windows bigger than the desktop. Each parameter is a pointer
+ to an integer where one dimension of the screen will be stored.
+
+
+ Under some OSes, switching to a full screen graphics mode may automatically
+ change the desktop resolution. You have, therefore, to call this function
+ before setting any graphics mode in order to retrieve the real desktop
+ resolution. Example:
+
+ int width, height;
+
+ allegro_init();
+ ...
+ if (get_desktop_resolution(&width, &height) == 0) {
+ /* Got the resolution correctly */
+ }
+
Return value:
+ Returns zero on success, or a negative number if this information is not
+ available or does not apply, in which case the values stored in the
+ variables you provided for `width' and `height' are undefined.
+
+
+
+ Detects the CPU type, setting the following global variables. You don't
+ normally need to call this, because allegro_init() will do it for you.
+
+
+
+ On Intel PCs, contains the CPU vendor name if known. On Mac OSX systems
+ this contains the PPC subtype name. On other platforms, this may be an empty
+ string. You can read this variable after you have called check_cpu()
+ (which is automatically called by allegro_init()).
+
+
+
+ Contains the Intel type, where applicable. Allegro defines the following
+ CPU family types:
+
+ CPU_FAMILY_UNKNOWN - The type of processor is unknown
+ CPU_FAMILY_I386 - The processor is an Intel-compatible 386
+ CPU_FAMILY_I486 - The processor is an Intel-compatible 486
+ CPU_FAMILY_I586 - The processor is a Pentium or equivalent
+ CPU_FAMILY_I686 - The processor is a Pentium Pro, II, III
+ or equivalent
+ CPU_FAMILY_ITANIUM - The processor is an Itanium processor
+ CPU_FAMILY_POWERPC - The processor is a PowerPC processor
+ CPU_FAMILY_EXTENDED - The processor type needs to be read
+ from the cpu_model
+
+ You can read this variable after you have called check_cpu()
+ (which is automatically called by allegro_init()).
+
+
+
+ Contains the CPU submodel, where applicable. Allegro defines at least the
+ following CPU family types (see include/allegro/system.h for a more
+ complete list):
+
+ You can read this variable after you have called check_cpu() (which is
+ automatically called by allegro_init()). Make sure you check the cpu_family
+ and cpu_vendor so you know which models make sense to check.
+
+
+
+ Contains CPU flags indicating what features are available on the current
+ CPU. The flags can be any combination of these:
+
+ CPU_ID - Indicates that the "cpuid" instruction is
+ available. If this is set, then all Allegro CPU
+ variables are 100% reliable, otherwise there
+ may be some mistakes.
+ CPU_FPU - An FPU is available.
+ CPU_IA64 - Running on Intel 64 bit CPU
+ CPU_AMD64 - Running on AMD 64 bit CPU
+ CPU_MMX - Intel MMX instruction set is available.
+ CPU_MMXPLUS - Intel MMX+ instruction set is available.
+ CPU_SSE - Intel SSE instruction set is available.
+ CPU_SSE2 - Intel SSE2 instruction set is available.
+ CPU_SSE3 - Intel SSE3 instruction set is available.
+ CPU_3DNOW - AMD 3DNow! instruction set is available.
+ CPU_ENH3DNOW - AMD Enhanced 3DNow! instruction set is
+ available.
+ CPU_CMOV - Pentium Pro "cmov" instruction is available.
+
+ You can check for multiple features by OR-ing the flags together.
+ For example, to check if the CPU has an FPU and MMX instructions
+ available, you'd do:
+
+ if ((cpu_capabilities & (CPU_FPU | CPU_MMX)) ==
+ (CPU_FPU | CPU_MMX)) {
+ printf("CPU has both an FPU and MMX instructions!\n");
+ }
+
+ You can read this variable after you have called check_cpu() (which is
+ automatically called by allegro_init()).
+
+
+
+
+
+There are several structures and types defined by Allegro which are used
+in many functions (like the BITMAP structure). This section of the manual
+describes their useful content from a user point of view when they don't fit
+very well any of the existing manual sections, and redirects you to the
+appropiate section when it's already described there. Note that unless stated
+otherwise, the contents shown here are just for read only purposes, there
+might be other internal flags, but you shouldn't depend on them being
+available in past/future versions of Allegro.
+
+
+ This is a fixed point integer which can replace float with similar results
+ and is faster than float on low end machines. Read chapter "Fixed point
+ math routines" for the full explanation.
+
+
+
+ int w, h; - size of the bitmap in pixels
+ int clip; - non-zero if clipping is turned on
+ int cl, cr, ct, cb; - clip rectangle left, right, top,
+ and bottom
+ unsigned char *line[]; - pointers to the start of each line
+
+ There is some other stuff in the structure as well, but it is liable to
+ change and you shouldn't use anything except the above. The `w' and `h'
+ fields can be used to obtain the size of an existing bitmap:
+
+ The clipping rectangle is inclusive on the left and top (0 allows drawing
+ to position 0) but exclusive on the right and bottom (10 allows drawing
+ to position 9, but not to 10). Note this is not the same format as that of
+ the clipping API, which takes inclusive coordinates for all four corners.
+ All the values of this structure should be regarded as read-only, with the
+ exception of the line field, whose access is described in depth in the
+ "Direct access to video memory" section of the manual. If you want to
+ modify the clipping region, please refrain from changing this structure.
+ Use set_clip_rect() instead.
+
+
+
+ int w, h; - width and height in pixels
+ int color_depth; - color depth of the image
+
+ RLE sprites store the image in a simple run-length encoded format, where
+ repeated zero pixels are replaced by a single length count, and strings of
+ non-zero pixels are preceded by a counter giving the length of the solid
+ run. Read chapter "RLE sprites" for a description of the restrictions and
+ how to obtain/use this structure.
+
+
+
+ short planar; - set if it's a planar (mode-X) sprite
+ short color_depth; - color depth of the image
+ short w, h; - size of the sprite
+
+ Compiled sprites are stored as actual machine code instructions that draw
+ a specific image onto a bitmap, using mov instructions with immediate data
+ values. Read chapter "Compiled sprites" for a description of the
+ restrictions and how to obtain/use this structure.
+
+
+
+ int flags; - status flags for this
+ joystick
+ int num_sticks; - how many stick inputs?
+ int num_buttons; - how many buttons?
+ JOYSTICK_STICK_INFO stick[n]; - stick state information
+ JOYSTICK_BUTTON_INFO button[n]; - button state information
+
+ Read chapter "Joystick routines" for a description on how to obtain/use
+ this structure.
+
+
+
+ int flags; - status flags for this
+ input
+ int num_axis; - how many axes do we
+ have? (note the misspelling)
+ JOYSTICK_AXIS_INFO axis[n]; - axis state information
+ char *name; - description of this
+ input
+
+ Read chapter "Joystick routines" for a description on how to obtain/use
+ this structure.
+
+
+
+ Palette entry. It contains an additional field for the purpose of padding
+ but you should not usually care about it. Read chapter "Palette routines"
+ for a description on how to obtain/use this structure.
+
+
+
+ fixed x, y, z; - position
+ fixed u, v; - texture map coordinates
+ int c; - color
+
+ A vertex structure used by polygon3d and other polygon rendering
+ functions. Read the description of polygon3d() for a description on how
+ to obtain/use this structure.
+
+
+
+ float x, y, z; - position
+ float u, v; - texture map coordinates
+ int c; - color
+
+ Like V3D but using float values instead of fixed ones. Read the
+ description of polygon3d_f() for a description on how to obtain/use this
+ structure.
+
+
+
+ void *dat; - pointer to the actual data
+ int type; - type of the data
+ long size; - size of the data in bytes
+ void *prop; - list of object properties
+
+ Read chapter "Datafile routines", section "Using datafiles" for a
+ description on how to obtain/use this structure.
+
+
+
+ int (*proc)(int, DIALOG *, int); - dialog procedure
+ (message handler)
+ int x, y, w, h; - position and size of the object
+ int fg, bg; - foreground and background colors
+ int key; - ASCII keyboard shortcut
+ int flags; - flags about the status of the object
+ int d1, d2; - whatever you want to use them for
+ void *dp, *dp2, *dp3; - pointers to more object-specific data
+
+ This is the structure which contains a GUI object. Read chapter "GUI
+ routines" for a description on how to obtain/use this structure.
+
+
+
+ char *text; - the text to display for the menu item
+ int (*proc)(void); - called when the menu item is clicked
+ struct MENU *child; - nested child menu
+ int flags; - disabled or checked state
+ void *dp; - pointer to any data you need
+
+ Structure used to hold an entry of a menu. Read chapter "GUI routines",
+ section "GUI menus" for a description on how to obtain/use this structure.
+
+
+
+ A structure which holds GUI data used internally by Allegro. Read the
+ documentation of init_dialog() for a description on how to obtain/use this
+ structure.
+
+
+
+ A structure which holds GUI data used internally by Allegro. Read the
+ documentation of init_menu() for a description on how to obtain/use this
+ structure.
+
+
+
+ A structure holding an Allegro font, usually created beforehand with the
+ grabber tool or Allegro's default font. Read chapter "Fonts" for a
+ description on how to load/destroy fonts, and chapter "Text output" for a
+ description on how to show text.
+
+
+
+ Structure used by Allegro's 3d zbuffered rendering functions. You are not
+ supposed to mix ZBUFFER with BITMAP even though it is currently possible
+ to do so. This is just an internal representation, and it may change in
+ the future.
+
+
+
+ int bits; - 8 or 16
+ int stereo; - sample type flag
+ int freq; - sample frequency
+ int priority; - 0-255
+ unsigned long len; - length (in samples)
+ unsigned long loop_start; - loop start position
+ unsigned long loop_end; - loop finish position
+ void *data; - raw sample data
+
+ A sample structure, which holds sound data, used by the digital sample
+ routines. You can consider all of these fields as read only except
+ priority, loop_start and loop_end, which you can change them for example
+ after loading a sample from disk.
+
+
+ The priority is a value from 0 to 255 (by default set to 128) and controls
+ how hardware voices on the sound card are allocated if you attempt to play
+ more than the driver can handle. This may be used to ensure that the less
+ important sounds are cut off while the important ones are preserved.
+
+
+ The variables loop_start and loop_end specify the loop position in sample
+ units, and are set by default to the start and end of the sample.
+
+
+ If you are creating your own samples on the fly, you might also want to
+ modify the raw data of the sample pointed by the data field. The sample
+ data are always in unsigned format. This means that if you are loading a
+ PCM encoded sound file with signed 16-bit samples, you would have to XOR
+ every two bytes (i.e. every sample value) with 0x8000 to change the
+ signedness.
+
+
+
+ int voice; - the hardware voice used for the sample
+
+ A structure holding an audiostream, which is a convenience wrapper around
+ a SAMPLE structure to double buffer sounds too big to fit into memory, or
+ do clever things like generating the sound wave real time.
+
+
+ While you shouldn't modify directly the value of the voice, you can use
+ all of the voice functions in chapter "Digital sample routines" to modify
+ the properties of the sound, like the frequency.
+
+
+
+ A packfile structure, similar to the libc FILE structure. Read chapter
+ "File and compression routines" for a description on how to obtain/use
+ this structure. Note that prior to version 4.1.18, some internal fields
+ were accidentally documented - but PACKFILE should be treated as an
+ opaque structure, just like the libc FILE type.
+
+
+
+ int pf_fclose(void *userdata);
+ int pf_getc(void *userdata);
+ int pf_ungetc(int c, void *userdata);
+ long pf_fread(void *p, long n, void *userdata);
+ int pf_putc(int c, void *userdata);
+ long pf_fwrite(const void *p, long n, void *userdata);
+ int pf_fseek(void *userdata, int offset);
+ int pf_feof(void *userdata);
+ int pf_ferror(void *userdata);
+
+ This is the vtable which must be provided for custom packfiles, which then
+ can read from and write to wherever you like (eg. files in memory). You
+ should provide all the entries of the vtable, even if they are empty stubs
+ doing nothing, to avoid Allegro (or you) calling a NULL method at some
+ point.
+
+
+
+ Opaque structure for handling LZSS compression. Read chapter "File and
+ compression routines for a description on how to obtain/use this
+ structure.
+
+
+
+ Opaque structure for handling LZSS decompression. Read chapter "File and
+ compression routines for a description on how to obtain/use this
+ structure.
+
+
+
+
+
uvsprintf — Writes formatted data into a buffer, using variable arguments.
+
uvszprintf — Writes formatted data into a buffer, using size and variable arguments.
+
uwidth — Low level helper function for testing Unicode text data.
+
uwidth_max — Number of bytes a character can occupy.
+
+
+
+Allegro can manipulate and display text using any character values from 0
+right up to 2^32-1 (although the current implementation of the grabber can
+only create fonts using characters up to 2^16-1). You can choose between a
+number of different text encoding formats, which controls how strings are
+stored and how Allegro interprets strings that you pass to it. This setting
+affects all aspects of the system: whenever you see a function that returns
+a char * type, or that takes a char * as an argument, that text will be in
+whatever format you have told Allegro to use.
+
+
+By default, Allegro uses UTF-8 encoded text (U_UTF8). This is a
+variable-width format, where characters can occupy anywhere from one to four
+bytes. The nice thing about it is that characters ranging from 0-127 are
+encoded directly as themselves, so UTF-8 is upwardly compatible with 7-bit
+ASCII ("Hello, World!" means the same thing regardless of whether you
+interpret it as ASCII or UTF-8 data). Any character values above 128, such
+as accented vowels, the UK currency symbol, and Arabic or Chinese
+characters, will be encoded as a sequence of two or more bytes, each in the
+range 128-255. This means you will never get what looks like a 7-bit ASCII
+character as part of the encoding of a different character value, which
+makes it very easy to manipulate UTF-8 strings.
+
+
+There are a few editing programs that understand UTF-8 format text files.
+Alternatively, you can write your strings in plain ASCII or 16-bit Unicode
+formats, and then use the Allegro textconv program to convert them into
+UTF-8.
+
+
+If you prefer to use some other text format, you can set Allegro to work
+with normal 8-bit ASCII (U_ASCII), or 16-bit Unicode (U_UNICODE) instead, or
+you can provide some handler functions to make it support whatever other
+text encoding you like (for example it would be easy to add support for 32
+bit UCS-4 characters, or the Chinese GB-code format).
+
+
+There is some limited support for alternative 8-bit codepages, via the
+U_ASCII_CP mode. This is very slow, so you shouldn't use it for serious
+work, but it can be handy as an easy way to convert text between different
+codepages. By default the U_ASCII_CP mode is set up to reduce text to a
+clean 7-bit ASCII format, trying to replace any accented vowels with their
+simpler equivalents (this is used by the allegro_message() function when it
+needs to print an error report onto a text mode DOS screen). If you want to
+work with other codepages, you can do this by passing a character mapping
+table to the set_ucodepage() function.
+
+
+Note that you can use the Unicode routines before you call install_allegro()
+or allegro_init(). If you want to work in a text mode other than UTF-8, it
+is best to set it with set_uformat() just before you call these.
+
+
+ Sets the current text encoding format. This will affect all parts of
+ Allegro, wherever you see a function that returns a char *, or takes a
+ char * as a parameter. `type' should be one of these values:
+
+ Although you can change the text format on the fly, this is not a good
+ idea. Many strings, for example the names of your hardware drivers and
+ any language translations, are loaded when you call allegro_init(), so if
+ you change the encoding format after this, they will be in the wrong
+ format, and things will not work properly. Generally you should only call
+ set_uformat() once, before allegro_init(), and then leave it on the same
+ setting for the duration of your program.
+
+
+
+ Finds out what text encoding format is currently selected. This function
+ is probably useful only if you are writing an Allegro addon dealing with
+ text strings and you use a different codepath for each possible format.
+ Example:
+
void register_uformat(int type,
+ int (*u_getc)(const char *s),
+ int (*u_getx)(char **s),
+ int (*u_setc)(char *s, int c),
+ int (*u_width)(const char *s),
+ int (*u_cwidth)(int c),
+ int (*u_isok)(int c));
+ Installs a set of custom handler functions for a new text encoding
+ format. The `type' is the ID code for your new format, which should be a
+ 4-character string as produced by the AL_ID() macro, and which can later
+ be passed to functions like set_uformat() and uconvert(). The function
+ parameters are handlers that implement the character access for your new
+ type: see below for details of these.
+
+
+
void set_ucodepage(const unsigned short *table,
+ const unsigned short *extras);
+ When you select the U_ASCII_CP encoding mode, a set of tables are used to
+ convert between 8-bit characters and their Unicode equivalents. You can
+ use this function to specify a custom set of mapping tables, which allows
+ you to support different 8-bit codepages.
+
+
+ The `table' parameter points to an array of 256 shorts, which contain the
+ Unicode value for each character in your codepage. The `extras' parameter,
+ if not NULL, points to a list of mapping pairs, which will be used when
+ reducing Unicode data to your codepage. Each pair consists of a Unicode
+ value, followed by the way it should be represented in your codepage.
+ The list is terminated by a zero Unicode value. This allows you to create
+ a many->one mapping, where many different Unicode characters can be
+ represented by a single codepage value (eg. for reducing accented vowels
+ to 7-bit ASCII).
+
+
+ Allegro will use the `table' parameter when it needs to convert an ASCII
+ string to an Unicode string. But when Allegro converts an Unicode string
+ to ASCII, it will use both parameters. First, it will loop through the
+ `table' parameter looking for an index position pointing at the unicode
+ value it is trying to convert (ie. the `table' parameter is also used for
+ reverse matching). If that fails, the `extras' list is used. If that fails
+ too, Allegro will put the character `^', giving up the conversion.
+
+
+ Note that Allegro comes with a default `table' and `extras' parameters
+ set internally. The default `table' will convert 8-bit characters to `^'.
+ The default `extras' list reduces Latin-1 and Extended-A characters to 7
+ bits in a sensible way (eg. an accented vowel will be reduced to the same
+ vowel without the accent).
+
+
+
int need_uconvert(const char *s, int type, int newtype);
+ Given a pointer to a string (`s'), a description of the type of the string
+ (`type'), and the type that you would like this string to be converted into
+ (`newtype'), this function tells you whether any conversion is required. No
+ conversion will be needed if `type' and `newtype' are the same, or if one
+ type is ASCII, the other is UTF-8, and the string contains only character
+ values less than 128. As a convenience shortcut, you can pass the value
+ U_CURRENT as either of the type parameters, to represent whatever text
+ encoding format is currently selected. Example:
+
+ if (need_uconvert(text, U_UTF8, U_CURRENT)) {
+ /* conversion is required */
+ }
+
Return value:
+ Returns non-zero if any conversion is required or zero otherwise.
+
+
+
int uconvert_size(const char *s, int type, int newtype);
+ Finds out how many bytes are required to store the specified string `s'
+ after a conversion from `type' to `newtype', including the mandatory zero
+ terminator of the string. You can use U_CURRENT for either `type' or
+ `newtype' as a shortcut to represent whatever text encoding format is
+ currently selected. Example:
+
void do_uconvert(const char *s, int type,
+ char *buf, int newtype, int size);
+ Converts the specified string `s' from `type' to `newtype', storing at most
+ `size' bytes into the output `buf'. The type parameters can use the value
+ U_CURRENT as a shortcut to represent the currently selected encoding
+ format. Example:
+
+ Note that, even for empty strings, your destination string must have at
+ least enough bytes to store the terminating null character of the string,
+ and your parameter size must reflect this. Otherwise, the debug version of
+ Allegro will abort at an assertion, and the release version of Allegro
+ will overrun the destination buffer.
+
+
+
char *uconvert(const char *s, int type,
+ char *buf, int newtype, int size);
+ Higher level function running on top of do_uconvert(). This function
+ converts the specified string `s' from `type' to `newtype', storing at most
+ `size' bytes into the output `buf' (including the terminating null
+ character), but it checks before doing the conversion, and doesn't bother
+ if the string formats are already the same (either both types are equal, or
+ one is ASCII, the other is UTF-8, and the string contains only 7-bit ASCII
+ characters).
+
+
+ As a convenience, if `buf' is NULL it will convert the string into an
+ internal static buffer and the `size' parameter will be ignored. You should
+ be wary of using this feature, though, because that buffer will be
+ overwritten the next time this routine is called, so don't expect the data
+ to persist across any other library calls. The static buffer may hold less
+ than 1024 characters, so you won't be able to convert large chunks of text.
+ Example:
+
Return value:
+ Returns a pointer to `buf' (or the static buffer if you used NULL) if a
+ conversion was performed. Otherwise returns a copy of `s'. In any cases,
+ you should use the return value rather than assuming that the string will
+ always be moved to `buf'.
+
+
+
+ Helper macro for converting strings from ASCII into the current encoding
+ format. Expands to uconvert(s, U_ASCII, buf, U_CURRENT, sizeof(buf)).
+
+
+
+ Helper macro for converting strings from the current encoding format into
+ ASCII. Expands to uconvert(s, U_CURRENT, buf, U_ASCII, sizeof(buf)).
+
+
+
+ You can't just rely on "" to be a valid empty string in any encoding
+ format. This global buffer contains a number of consecutive zeros, so it
+ will be a valid empty string no matter whether the program is running in
+ ASCII, Unicode, or UTF-8 mode.
+
+
Return value:
+ Returns the character pointed to by `s' in the current encoding format, and
+ advances the pointer to the next character after the one just returned.
+
+
+
+ Low level helper function for testing Unicode text data. Finds out if the
+ character value `c' can be encoded correctly in the current format, which
+ can be useful if you are converting from Unicode to ASCII or another
+ encoding format where the range of valid characters is limited.
+
Return value:
+ Returns non-zero if the value can be correctly encoded, zero otherwise.
+
+
+
+ Finds out the offset (in bytes from the start of the string) of the
+ character at the specified `index' in the string `s'. A zero `index'
+ parameter will return the first character of the string. If `index' is
+ negative, it counts backward from the end of the string, so an `index' of
+ `-1' will return an offset to the last character. Example:
+
+ int from_third_letter = uoffset(text_string, 2);
+
Return value:
+ Returns the offset in bytes to the specified character.
+
+
+
+ Finds out the character value at the specified `index' in the string. A
+ zero `index' parameter will return the first character of the string. If
+ `index' is negative, it counts backward from the end of the string, so an
+ `index' of `-1' will return the last character of the string. Example:
+
+ Replaces the character at the specified index in the string with value `c',
+ handling any adjustments for variable width data (ie. if `c' encodes to a
+ different width than the previous value at that location). If `index' is
+ negative, it counts backward from the end of the string. Example:
+
Return value:
+ Returns the number of bytes by which the trailing part of the string was
+ moved. This is of interest only with text encoding formats where
+ characters have a variable length, like UTF-8.
+
+
+
+ Inserts the character `c' at the specified `index' in the string, sliding
+ the rest of the data along to make room. If `index' is negative, it counts
+ backward from the end of the string. Example:
+
+ Removes the character at the specified `index' within the string, sliding
+ the rest of the data back to fill the gap. If `index' is negative, it
+ counts backward from the end of the string. Example:
+
+ Low level helper function for working with Unicode text data. Returns the
+ largest number of bytes that one character can occupy in the given
+ encoding format. Pass U_CURRENT to represent the current format. Example:
+
+ This functions copies the null-terminated string `src' into a newly
+ allocated area of memory, effectively duplicating it. Example:
+
+ void manipulate_string(const char *input_string)
+ {
+ char *temp_buffer = ustrdup(input_string);
+ /* Now we can modify temp_buffer */
+ ...
+
Return value:
+ Returns the newly allocated string. This memory must be freed by the
+ caller. Returns NULL if it cannot allocate space for the duplicated string.
+
+
+
+ This function copies `src' (including the terminating null character into
+ `dest'. You should try to avoid this function because it is very easy to
+ overflow the destination buffer. Use ustrzcpy instead.
+
char *ustrzcpy(char *dest, int size, const char *src);
+ This function copies `src' (including the terminating NULL character into
+ `dest', whose length in bytes is specified by `size' and which is
+ guaranteed to be null-terminated even if `src' is bigger than `size'.
+
+
+ Note that, even for empty strings, your destination string must have at
+ least enough bytes to store the terminating null character of the string,
+ and your parameter size must reflect this. Otherwise, the debug version of
+ Allegro will abort at an assertion, and the release version of Allegro
+ will overrun the destination buffer.
+
Return value:
+ Returns the value of `dest'.
+
+
+
+ This function concatenates `src' to the end of `dest`'. You should try to
+ avoid this function because it is very easy to overflow the destination
+ buffer, use ustrzcat instead.
+
Return value:
+ Returns the value of `dest'.
+
+
+
char *ustrzcat(char *dest, int size, const char *src);
+ This function concatenates `src' to the end of `dest', whose length in
+ bytes is specified by `size' and which is guaranteed to be null-terminated
+ even when `src' is bigger than `size'.
+
+
+ Note that, even for empty strings, your destination string must have at
+ least enough bytes to store the terminating null character of the string,
+ and your parameter size must reflect this. Otherwise, the debug version of
+ Allegro will abort at an assertion, and the release version of Allegro
+ will overrun the destination buffer.
+
Return value:
+ Returns the value of `dest'.
+
+
+
Return value:
+ Returns zero if the strings are equal, a positive number if `s1' comes
+ after `s2' in the ASCII collating sequence, else a negative number.
+
+
+
char *ustrncpy(char *dest, const char *src, int n);
+ This function is like ustrcpy() except that no more than `n' characters
+ from `src' are copied into `dest'. If `src' is shorter than `n' characters,
+ null characters are appended to `dest' as padding until `n' characters have
+ been written.
+
+
+ Note that if `src' is longer than `n' characters, `dest' will not be
+ null-terminated.
+
Return value:
+ The return value is the value of `dest'.
+
+
+
char *ustrzncpy(char *dest, int size, const char *src, int n);
+ This function is like ustrzcpy() except that no more than `n' characters
+ from `src' are copied into `dest'. If `src' is shorter than `n' characters,
+ null characters are appended to `dest' as padding until `n' characters have
+ been written. In any case, `dest' is guaranteed to be null-terminated.
+
+
+ Note that, even for empty strings, your destination string must have at
+ least enough bytes to store the terminating null character of the string,
+ and your parameter `size' must reflect this. Otherwise, the debug version
+ of Allegro will abort at an assertion, and the release version of Allegro
+ will overrun the destination buffer.
+
Return value:
+ The return value is the value of `dest'.
+
+
+
char *ustrncat(char *dest, const char *src, int n);
+ This function is like ustrcat() except that no more than `n' characters
+ from `src' are appended to the end of `dest'. If the terminating null
+ character in `src' is reached before `n' characters have been written, the
+ null character is copied, but no other characters are written. If `n'
+ characters are written before a terminating null is encountered, the
+ function appends its own null character to `dest', so that `n+1' characters
+ are written. You should try to avoid this function because it is very
+ easy to overflow the destination buffer. Use ustrzncat instead.
+
Return value:
+ The return value is the value of `dest'.
+
+
+
char *ustrzncat(char *dest, int size, const char *src, int n);
+ This function is like ustrzcat() except that no more than `n' characters
+ from `src' are appended to the end of `dest'. If the terminating null
+ character in `src' is reached before `n' characters have been written, the
+ null character is copied, but no other characters are written. Note that
+ `dest' is guaranteed to be null-terminated.
+
Return value:
+ The return value is the value of `dest'.
+
+
+
int ustrncmp(const char *s1, const char *s2, int n);
+ This function compares up to `n' characters of `s1' and `s2'. Example:
+
+ if (ustrncmp(prefix, long_string, ustrlen(prefix)) == 0) {
+ /* long_string starts with prefix */
+ }
+
Return value:
+ Returns zero if the substrings are equal, a positive number if `s1' comes
+ after `s2' in the ASCII collating sequence, else a negative number.
+
+
+
+ This function compares `s1' and `s2', ignoring case. Example:
+
+ if (ustricmp(string, user_input) == 0) {
+ /* string and user_input are equal (ignoring case) */
+ }
+
Return value:
+ Returns zero if the strings are equal, a positive number if `s1' comes
+ after `s2' in the ASCII collating sequence, else a negative number.
+
+
+
int ustrnicmp(const char *s1, const char *s2, int n);
+ This function compares up to `n' characters of `s1' and `s2', ignoring
+ case. Example:
+
+ if (ustrnicmp(prefix, long_string, ustrlen(prefix)) == 0) {
+ /* long_string starts with prefix (ignoring case) */
+ }
+
Return value:
+ Returns zero if the strings are equal, a positive number if `s1' comes
+ after `s2' in the ASCII collating sequence, else a negative number.
+
+
+
Return value:
+ Returns a pointer to the first occurrence of `c' in `s', or NULL if no
+ match was found. Note that if `c' is NULL, this will return a pointer to
+ the end of the string.
+
+
+
+ This function retrieves tokens from `s' which are delimited by characters
+ from `set'. To initiate the search, pass the string to be searched as `s'.
+ For the remaining tokens, pass NULL instead. Warning: Since ustrtok alters
+ the string it is parsing, you should always copy the string to a temporary
+ buffer before parsing it. Also, this function is not reentrant (ie. you
+ cannot parse two strings at the same time). Example:
+
+ char *word;
+ char string[]="some-words with dashes";
+ char *temp = ustrdup(string);
+ word = ustrtok(temp, " -");
+ while (word) {
+ allegro_message("Found `%s'\n", word);
+ word = ustrtok(NULL, " -");
+ }
+ free(temp);
+
Return value:
+ Returns a pointer to the token, or NULL if no more are found.
+
+
+
+ Reentrant version of ustrtok. The `last' parameter is used to keep track
+ of where the parsing is up to and must be a pointer to a char * variable
+ allocated by the user that remains the same while parsing the same
+ string. Example:
+
+ char *word, *last;
+ char string[]="some-words with dashes";
+ char *temp = ustrdup(string);
+ word = ustrtok_r(string, " -", &last);
+ while (word) {
+ allegro_message("Found `%s'\n", word);
+ word = ustrtok_r(NULL, " -", &last);
+ }
+ free(temp);
+
Return value:
+ Returns a pointer to the token, or NULL if no more are found. You can free
+ the memory pointed to by `last' once NULL is returned.
+
+
+
long ustrtol(const char *s, char **endp, int base);
+ This function converts the initial part of `s' to a signed integer, setting
+ `*endp' to point to the first unused character, if `endp' is not a NULL
+ pointer. The `base' argument indicates what base the digits (or letters)
+ should be treated as. If `base' is zero, the base is determined by looking
+ for `0x', `0X', or `0' as the first part of the string, and sets the base
+ used to 16, 16, or 8 if it finds one. The default base is 10 if none of
+ those prefixes are found. Example:
+
+ char *endp, *string = "456.203 askdfg";
+ int number = ustrtol(string, &endp, 10);
+
Return value:
+ Returns the string converted as a value of type `long int'. If nothing was
+ converted, returns zero with `*endp' pointing to the beginning of `s'.
+
+
+
+ This function converts as many characters of `s' that look like a floating
+ point number into one, and sets `*endp' to point to the first unused
+ character, if `endp' is not a NULL pointer. Example:
+
Return value:
+ Returns the string converted as a value of type `double'. If nothing was
+ converted, returns zero with *endp pointing to the beginning of s.
+
+
+
Return value:
+ Returns a pointer to a static string that should not be modified or
+ freed. If you make subsequent calls to ustrerror(), the string will be
+ overwritten.
+
+
+
+ This function writes formatted data into the output buffer. A NULL
+ character is written to mark the end of the string. You should try to avoid
+ this function because it is very easy to overflow the destination buffer.
+ Use uszprintf instead.
+
Return value:
+ Returns the number of characters written, not including the terminating
+ null character.
+
+
+
int uszprintf(char *buf, int size, const char *format, ...);
+ This function writes formatted data into the output buffer, whose length
+ in bytes is specified by `size' and which is guaranteed to be NULL
+ terminated. Example:
+
+ char buffer[10];
+ int player_score;
+ ...
+ uszprintf(buffer, sizeof(buffer), "Your score is: %d", player_score);
+
Return value:
+ Returns the number of characters that would have been written without
+ eventual truncation (like with usprintf), not including the terminating
+ null character.
+
+
+
int uvsprintf(char *buf, const char *format, va_list args);
+ This is like usprintf(), but you pass the variable argument list directly,
+ instead of the arguments themselves. You can use this function to implement
+ printf like functions, also called variadic functions. You should try to
+ avoid this function because it is very easy to overflow the destination
+ buffer. Use uvszprintf instead.
+
Return value:
+ Returns the number of characters written, not including the terminating
+ null character.
+
+
+
Return value:
+ Returns the number of characters that would have been written without
+ eventual truncation (like with uvsprintf), not including the terminating
+ null character.
+
+
+
+
+
+Various parts of Allegro, such as the sound routines and the
+load_joystick_data() function, require some configuration information. This
+data is stored in text files as a collection of `variable=value' lines,
+along with comments that begin with a `#' character and continue to the end
+of the line. The configuration file may optionally be divided into sections,
+which begin with a `[sectionname]' line. Each section has a unique
+namespace, to prevent variable name conflicts, but any variables that aren't
+in a section are considered to belong to all the sections simultaneously.
+
+
+By default the configuration data is read from a file called `allegro.cfg',
+which can be located either in the same directory as the program executable,
+or the directory pointed to by the ALLEGRO environment variable. Under Unix,
+it also checks for `~/allegro.cfg', `~/.allegrorc', `/etc/allegro.cfg', and
+`/etc/allegrorc', in that order; under BeOS only the last two are also
+checked. MacOS X also checks in the Contents/Resources directory of the
+application bundle, if any, before doing the checks above.
+
+
+If you don't like this approach, you can specify any filename you like, or
+use a block of binary configuration data provided by your program (which
+could for example be loaded from a datafile). You can also extend the paths
+searched for allegro resources with set_allegro_resource_path().
+
+
+You can store whatever custom information you like in the config file, along
+with the standard variables that are used by Allegro (see below). Allegro
+comes with a setup directory where you can find configuration programs. The
+standalone setup program is likely to be of interest to final users. It
+allows any user to create an `allegro.cfg' file without the need to touch a
+text editor and enter values by hand. It also provides a few basic tests like
+sound playing for soundcard testing. You are welcome to include the setup
+program with your game, either as is or with modified graphics to fit better
+your game.
+
+
+ Sets the configuration file to be used by all subsequent config
+ functions. If you don't call this function, Allegro will use the default
+ `allegro.cfg' file, looking first in the same directory as your program
+ and then in the directory pointed to by the ALLEGRO environment variable
+ and the usual platform-specific paths for configuration files. For example
+ it will look for `/etc/allegro.cfg' under Unix.
+
+
+ All pointers returned by previous calls to get_config_string() and
+ other related functions are invalidated when you call this function!
+ You can call this function before install_allegro() to change the
+ configuration file, but after set_uformat() if you want to use a text
+ encoding format other than the default.
+
+
+
+ Specifies a block of data to be used by all subsequent config functions,
+ which you have already loaded from disk (eg. as part of some more
+ complicated format of your own, or in a grabber datafile). This routine
+ makes a copy of the information, so you can safely free the data after
+ calling it.
+
+
+
+ Specifies a file containing config overrides. These settings will be used
+ in addition to the parameters in the main config file, and where a
+ variable is present in both files this version will take priority. This
+ can be used by application programmers to override some of the config
+ settings from their code, while still leaving the main config file free
+ for the end user to customise. For example, you could specify a
+ particular sample frequency and IBK instrument file, but the user could
+ still use an `allegro.cfg' file to specify the port settings and irq
+ numbers.
+
+
+ The override config file will not only take precedence when reading, but
+ will also be used for storing values. When you are done with using the
+ override config file, you can call override_config_file with a NULL
+ parameter, so config data will be directly read from the current config
+ file again.
+
+
+ Note: The override file is completely independent from the current
+ configuration. You can e.g. call set_config_file, and the override file
+ will still be active. Also the flush_config_file function will only affect
+ the current config file (which can be changed with set_config_file), never
+ the overriding one specified with this function. The modified override
+ config is written back to disk whenever you call override_config_file.
+
+
+ Example:
+
+ override_config_file("my.cfg");
+ /* This will read from my.cfg, and if it doesn't find a
+ * setting, will read from the current config file instead.
+ */
+ language = get_config_string("system", "language", NULL);
+ /* This will always write to my.cfg, no matter if the
+ * settings is already present or not.
+ */
+ set_config_string("system", "language", "RU");
+ /* This forces the changed setting to be written back to
+ * disk. Else it is written back at the next call to
+ * override_config_file, or when Allegro shuts down.
+ */
+ override_config_file(NULL);
+
+
+ Note that this function and override_config_data() are mutually exclusive,
+ i.e. calling one will cancel the effects of the other.
+
+
+
+ Version of override_config_file() which uses a block of data that has
+ already been read into memory. The length of the block has to be specified
+ in bytes. Example:
+
+ /* Force German as system language, Spanish keyboard map. */
+ const char *override_data = "[system]\n"
+ "language=DE\n"
+ "keyboard=ES";
+ override_config_data(override_data, ustrsize(override_data));
+
+
+ Note that this function and override_config_file() are mutually exclusive,
+ i.e. calling one will cancel the effects of the other.
+
+
+
+ Pushes the current configuration state (filename, variable values, etc).
+ onto an internal stack, allowing you to select some other config source
+ and later restore the current settings by calling pop_config_state().
+ This function is mostly intended for internal use by other library
+ functions, for example when you specify a config filename to the
+ save_joystick_data() function, it pushes the config state before
+ switching to the file you specified.
+
+
+
+ Reloads the translated strings returned by get_config_text(). This is
+ useful to switch to another language in your program at runtime. If you
+ want to modify the `[system]' language configuration variable yourself, or
+ you have switched configuration files, you will want to pass NULL to
+ just reload whatever language is currently selected. Or you can pass a
+ string containing the two letter code of the language you desire to
+ switch to, and the function will modify the language variable. After you
+ call this function, the previously returned pointers of get_config_text()
+ will be invalid. Example:
+
+ ...
+ /* The user selects French from a language choice menu. */
+ reload_config_texts("FR");
+ Takes control of the specified config file section, so that your hook
+ functions will be used to manipulate it instead of the normal disk file
+ access. If both the getter and setter functions are NULL, a currently
+ present hook will be unhooked. Hooked functions have the highest
+ priority. If a section is hooked, the hook will always be called, so you
+ can also hook a '#' section: even override_config_file() cannot override
+ a hooked section. Example:
+
+ int decode_encrypted_int(const char *name, int def)
+ {
+ ...
+ }
+
+ const char *decode_encrypted_string(const char *name, const char *def)
+ {
+ ...
+ }
+
+ void encode_plaintext_string(const char *name, const char *value)
+ {
+ ...
+ }
+
+ int main(int argc, char *argv[])
+ {
+ ...
+ /* Make it harder for users to tinker with the high scores. */
+ hook_config_section("high_scores", decode_encrypted_int,
+ decode_encrypted_string, encode_plaintext_string);
+ ...
+ } END_OF_MAIN()
+ Retrieves a string variable from the current config file. The section name
+ may be set to NULL to read variables from the root of the file, or used to
+ control which set of parameters (eg. sound or joystick) you are interested
+ in reading. Example:
+
Return value:
+ Returns a pointer to the constant string found in the configuration file.
+ If the named variable cannot be found, or its entry in the config file is
+ empty, the value of `def' is returned.
+
+
+
char **get_config_argv(const char *section, const char *name, int *argc);
+ Reads a token list (words separated by spaces) from the current config
+ file. The token list is stored in a temporary buffer that will be clobbered
+ by the next call to get_config_argv(), so the data should not be expected
+ to persist.
+
Return value:
+ Returns an argv style argument list and sets `argc' to the number of
+ retrieved tokens. If the variable is not present, returns NULL and sets
+ argc to zero.
+
+
+
+ This function is primarily intended for use by internal library code, but
+ it may perhaps be helpful to application programmers as well. It uses the
+ `language.dat' or `XXtext.cfg' files (where XX is a language code) to look
+ up a translated version of the parameter in the currently selected
+ language.
+
+
+ This is basically the same thing as calling get_config_string() with
+ `[language]' as the section, `msg' as the variable name, and `msg' as the
+ default value, but it contains some special code to handle Unicode format
+ conversions. The `msg' parameter is always given in ASCII format, but the
+ returned string will be converted into the current text encoding, with
+ memory being allocated as required, so you can assume that this pointer
+ will persist without having to manually allocate storage space for each
+ string.
+
+
+ Note that if you are planning on distributing your game on the Unix
+ platform there is a special issue with how to deal with the `language.dat'
+ file. Read section "Files shared by Allegro" of the chapter "Unix
+ specifics" to learn more about this.
+
Return value:
+ Returns a suitable translation if one can be found or a copy of the
+ parameter if nothing else is available.
+
+
+
+ Writes a string variable to the current config file, replacing any
+ existing value it may have, or removes the variable if `val' is NULL. The
+ section name may be set to NULL to write the variable to the root of the
+ file, or used to control which section the variable is inserted into. The
+ altered file will be cached in memory, and not actually written to disk
+ until you call allegro_exit(). Note that you can only write to files in
+ this way, so the function will have no effect if the current config
+ source was specified with set_config_data() rather than set_config_file().
+
+
+ As a special case, variable or section names that begin with a '#'
+ character are treated specially and will not be read from or written to
+ the disk. Addon packages can use this to store version info or other
+ status information into the config module, from where it can be read with
+ the get_config_string() function.
+
+
+
+ This function can be used to get a list of all entries in the given config
+ section. The names parameter is a pointer to an array of strings. If it
+ points to a NULL pointer, the list will be allocated, else it will be
+ re-allocated. You should free the list again with free_config_entries if you
+ don't need it anymore, or you can pass it again to list_config_entries and
+ the memory will be re-used. See the following example for how you can use it,
+ it will print out the complete contents of the current configuration:
+
+ int i, n;
+ char const **sections = NULL;
+ char const **entries = NULL;
+
+ n = list_config_sections(§ions);
+ /* loop through all section names */
+ for (i = 0; i < n; i++)
+ {
+ int j, m;
+ printf("%s\n", sections[i]);
+ m = list_config_entries(sections[i], &entries);
+ /* loop through all entries in the section */
+ for (j = 0; j < m; j++)
+ {
+ printf(" %s=\"%s\"\n", entries[j], get_config_string(
+ sections[i], entries[j], "-"));
+ }
+ }
+ free_config_entries(§ions);
+ free_config_entries(&entries);
+
Return value:
+ Returns the number of valid strings in the names array.
+
+
+
+ The names parameter is a pointer to an array of strings. If it points to a
+ NULL pointer, the list will be allocated, else it will be re-allocated. After
+ the function returns, it will contain the names of all sections in the
+ current configuration. Use free_config_entries to free the allocated memory
+ again. See list_config_entries for more information and an example how to use
+ it.
+
Return value:
+ Returns the number of valid strings in the names array.
+
+
+
+ Once you are done with the string arrays filled in by list_config_entries and
+ list_config_sections, you can free them again with this function. The passed
+ array pointer will be set to NULL, and you directly can pass the same pointer
+ again to list_config_entries or list_config_sections later - but you also
+ could pass them again without freeing first, since the memory is re-allocated
+ when the pointer is not NULL.
+
+
+ See list_config_entries for an example of how to use it.
+
+
+
+Allegro uses these standard variables from the configuration file:
+
+[system]
+ Section containing general purpose variables:
+
+system = x
+ Specifies which system driver to use. This is currently only useful on
+ Linux, for choosing between the XWindows ("XWIN") or console ("LNXC")
+ modes.
+
+keyboard = x
+ Specifies which keyboard layout to use. The parameter is the name of a
+ keyboard mapping file produced by the keyconf utility, and can either be
+ a fully qualified file path or a basename like `us' or `uk'. If the
+ latter, Allegro will look first for a separate config file with that name
+ (eg. `uk.cfg') and then for an object with that name in the `keyboard.dat'
+ file (eg. `UK_CFG'). The config file or `keyboard.dat' file can be stored
+ in the same directory as the program, or in the location pointed to by
+ the ALLEGRO environment variable. Look in the `keyboard.dat' file to see
+ what mappings are currently available.
+
+language = x
+ Specifies which language file to use for error messages and other bits of
+ system text. The parameter is the name of a translation file, and can
+ either be a fully qualified file path or a basename like `en' or `es'. If
+ the latter, Allegro will look first for a separate config file with a
+ name in the form `entext.cfg', and then for an object with that name in
+ the `language.dat' file (eg. `ENTEXT_CFG'). The config file or
+ `language.dat' file can be stored in the same directory as the program, or
+ in the location pointed to by the ALLEGRO environment variable.
+
+ Look in the `language.dat' file to see which mappings are currently
+ available. If there is none for your language, you can create it using the
+ English one as model, and even send it to the Allegro development team to
+ include it in future releases.
+
+disable_screensaver = x
+ Specifies whether to disable the screensaver: 0 to never disable it, 1 to
+ disable it in fullscreen mode only and 2 to always disable it. Default is 1.
+
+menu_opening_delay = x
+ Sets how long the menus take to auto-open. The time is given in
+ milliseconds (default is `300'). Specifying `-1' will disable the
+ auto-opening feature.
+
+XInitThreads = x
+ If this is set to 0, the X11 port will not call XInitThreads. This can have
+ slight performance advantages and was required on some broken X11 servers,
+ but it makes Allegro incompatible with other X11 libraries like Mesa.
+
+[graphics]
+ Section containing graphics configuration information, using the
+ variables:
+
+gfx_card = x
+ Specifies which graphics driver to use when the program requests
+ GFX_AUTODETECT. Multiple possible drivers can be suggested with extra
+ lines in the form `gfx_card1 = x', `gfx_card2 = x', etc, or you can
+ specify different drivers for each mode and color depth with variables in
+ the form `gfx_card_24bpp = x', `gfx_card_640x480x16 = x', etc.
+
+gfx_cardw = x
+ Specifies which graphics driver to use when the program requests
+ GFX_AUTODETECT_WINDOWED. This variable functions exactly like
+ gfx_card in all other respects. If it is not set, Allegro will look
+ for the gfx_card variable.
+
+disable_vsync = x
+ Specifies whether to disable synchronization with the vertical blank when
+ page-flipping (yes or no). Disabling synchronization may increase the
+ frame rate on slow systems, at the expense of introducing flicker on fast
+ systems.
+
+vbeaf_driver = x
+ DOS and Linux only: specifies where to look for the VBE/AF driver
+ (vbeaf.drv). If this variable is not set, Allegro will look in the same
+ directory as the program, and then fall back on the standard locations
+ (`c:\' for DOS, `/usr/local/lib', `/usr/lib', `/lib', and `/' for Linux, or
+ the directory specified with the VBEAF_PATH environment variable).
+
+framebuffer = x
+ Linux only: specifies what device file to use for the fbcon driver. If
+ this variable is not set, Allegro checks the FRAMEBUFFER environment
+ variable, and then defaults to `/dev/fb0'.
+
+force_centering = x
+ Unix/X11 only: specifies whether to force window centering in fullscreen
+ mode when the XWFS driver is used (yes or no). Enabling this setting may
+ cause some artifacts to appear on KDE desktops.
+
+disable_direct_updating = x
+ Windows only: specifies whether to disable direct updating when the
+ GFX_DIRECTX_WIN driver is used in color conversion mode (yes or no).
+ Direct updating can cause artifacts to be left on the desktop when the
+ window is moved or minimized; disabling it results in a significant
+ performance loss.
+
+[mouse]
+ Section containing mouse configuration information, using the variables:
+
+mouse = x
+ Mouse driver type. Available DOS drivers are:
+
+ MICK - mickey mode driver (normally the best)
+ I33 - int 0x33 callback driver
+ POLL - timer polling (for use under NT)
+
+ Linux console mouse drivers are:
+
+ MS - Microsoft serial mouse
+ IMS - Microsoft serial mouse with Intellimouse extension
+ LPS2 - PS2 mouse
+ LIPS - PS2 mouse with Intellimouse extension
+ GPMD - GPM repeater data (Mouse Systems protocol)
+ EV - Event interfaces (EVDEV)
+
+num_buttons = x
+ Sets the number of mouse buttons viewed by Allegro. You don't normally
+ need to set this variable because Allegro will autodetect it. You can only
+ use it to restrict the set of actual mouse buttons to zero or positive
+ values, negative values will be ignored.
+
+emulate_three = x
+ Sets whether to emulate a third mouse button by detecting chords of the
+ left and right buttons (yes or no). Defaults to no.
+
+mouse_device = x
+ Linux only: specifies the name of the mouse device file (eg.
+ `/dev/mouse').
+
+ev_absolute = x
+ Linux only: specifies the mode for the default EV input:
+ 0 - relative mode: pointer position changes if the input moves,
+ 1 - absolute mode: pointer position is the input position.
+ If unspecified, the mode is relative.
+ If the device supports several tools (such as a graphic tablet), the
+ default input is the mouse. If the device has only one tool (e.g. a
+ normal mouse) the default input is this tool. All additionnal tools
+ work in absolute mode.
+
+ev_min_x = x
+ev_max_x = x
+ev_min_y = x
+ev_max_y = x
+ev_min_z = x
+ev_max_z = x
+ Linux only: for absolute EV inputs, minimum and maximum value. By default
+ this information is autodetected. If you want to use only part of a
+ tablet, you need to set the entries for X and Y axis by hand.
+
+ev_abs_to_rel_x = x
+ev_abs_to_rel_y = x
+ev_abs_to_rel_z = x
+ Linux only: scaling factor for tablet mouse speed. Defaults to 1.
+ This is used only when the input sends absolute events (tablet, joystick,
+ etc.) and the cursor should behave like a mouse.
+ If you are using a mouse on a tablet, you need to set these entries
+ for X and Y axis (try numbers between 1 and 40).
+
+mouse_accel_factor = x
+ Windows only: specifies the mouse acceleration factor. Defaults to 1.
+ Set it to 0 in order to disable mouse acceleration. 2 accelerates twice
+ as much as 1.
+
+[sound]
+ Section containing sound configuration information, using the variables:
+
+digi_card = x
+ Sets the driver to use for playing digital samples.
+
+midi_card = x
+ Sets the driver to use for MIDI music.
+
+digi_input_card = x
+ Sets the driver to use for digital sample input.
+
+midi_input_card = x
+ Sets the driver to use for MIDI data input.
+
+digi_voices = x
+ Specifies the minimum number of voices to reserve for use by the digital
+ sound driver. How many are possible depends on the driver.
+
+midi_voices = x
+ Specifies the minimum number of voices to reserve for use by the MIDI
+ sound driver. How many are possible depends on the driver.
+
+digi_volume = x
+ Sets the volume for digital sample playback, from 0 to 255.
+
+midi_volume = x
+ Sets the volume for midi music playback, from 0 to 255.
+
+quality = x
+ Controls the sound quality vs. performance tradeoff for the sample mixing
+ code. This can be set to any of the values:
+ 0 - fast mixing of 8-bit data into 16-bit buffers
+ 1 - true 16-bit mixing (requires a 16-bit stereo soundcard)
+ 2 - interpolated 16-bit mixing
+
+flip_pan = x
+ Toggling this between 0 and 1 reverses the left/right panning of samples,
+ which might be needed because some SB cards get the stereo image the wrong
+ way round.
+
+sound_freq = x
+ DOS, Unix and BeOS: sets the sample frequency. With the SB driver,
+ possible rates are 11906 (any), 16129 (any), 22727 (SB 2.0 and above),
+ and 45454 (only on SB 2.0 or SB16, not the stereo SB Pro driver). On the
+ ESS Audiodrive, possible rates are 11363, 17046, 22729, or 44194. On the
+ Ensoniq Soundscape, possible rates are 11025, 16000, 22050, or 48000. On
+ the Windows Sound System, possible rates are 11025, 22050, 44100, or
+ 48000. Don't worry if you set some other number by mistake: Allegro will
+ automatically round it to the closest supported frequency.
+
+sound_bits = x
+ Unix and BeOS: sets the preferred number of bits (8 or 16).
+
+sound_stereo = x
+ Unix and BeOS: selects mono or stereo output (0 or 1).
+
+sound_port = x
+ DOS only: sets the soundcard port address (this is usually 220).
+
+sound_dma = x
+ DOS only: sets the soundcard DMA channel (this is usually 1).
+
+sound_irq = x
+ DOS only: sets the soundcard IRQ number (this is usually 7).
+
+fm_port = x
+ DOS only: sets the port address of the OPL synth (this is usually 388).
+
+mpu_port = x
+ DOS only: sets the port address of the MPU-401 MIDI interface (this is
+ usually 330).
+
+mpu_irq = x
+ DOS only: sets the IRQ for the MPU-401 (this is usually the same as
+ sound_irq).
+
+ibk_file = x
+ DOS only: specifies the name of a .IBK file which will be used to replace
+ the standard Adlib patch set.
+
+ibk_drum_file = x
+ DOS only: specifies the name of a .IBK file which will be used to replace
+ the standard set of Adlib percussion patches.
+
+oss_driver = x
+ Unix only: sets the OSS device driver name. Usually `/dev/dsp' or
+ `/dev/audio', but could be a particular device (e.g. `/dev/dsp2').
+
+oss_numfrags = x
+oss_fragsize = x
+ Unix only: sets number of OSS driver fragments (buffers) and size of each
+ buffer in samples. Buffers are filled with data in the interrupts where
+ interval between subsequent interrupts is not less than 10 ms. If
+ hardware can play all information from buffers faster than 10 ms, then
+ there will be clicks, when hardware have played all data and library has
+ not prepared new data yet. On the other hand, if it takes too long for
+ device driver to play data from all buffers, then there will be delays
+ between action which triggers sound and sound itself.
+
+oss_midi_driver = x
+ Unix only: sets the OSS MIDI device name. Usually `/dev/sequencer'.
+
+oss_mixer_driver = x
+ Unix only: sets the OSS mixer device name. Usually `/dev/mixer'.
+
+esd_server = x
+ Unix only: where to find the ESD (Enlightened Sound Daemon) server.
+
+alsa_card = x
+alsa_pcmdevice = x
+ Unix only: card number and PCM device for the ALSA 0.5 sound driver.
+
+alsa_device = x
+ Unix only: device name for the ALSA 0.9 sound driver. The format is
+ <driver>[:<card>,<device>], for example: `hw:0,1'.
+
+alsa_mixer_device = x
+ Unix only: mixer device name for the ALSA 0.9 sound driver. The
+ default is "default".
+
+alsa_mixer_elem = x
+ Unix only: mixer element name for the ALSA 0.9 driver. The default
+ is PCM.
+
+alsa_numfrags = x
+ Unix only: number of ALSA driver fragments (buffers).
+
+alsa_fragsize = x
+ Unix only: size of each ALSA fragment, in samples.
+
+alsa_rawmidi_card = x
+ Unix only: card number and device for the ALSA 0.5 midi driver.
+
+alsa_rawmidi_device = x
+ Unix only: device for the ALSA 0.5 midi driver or device name for
+ the ALSA 0.9 midi driver (see alsa_device for the format).
+
+jack_client_name = x
+ Sets the name with which Allegro should identify itself to the Jack
+ audio server.
+
+jack_buffer_size = x
+ Forces a buffer size for the transfer buffer from Allegro's mixer
+ to Jack.
+
+be_midi_freq = x
+ BeOS only: MIDI sample mixing frequency in Hz. Can be 11025, 22050 or
+ 44100.
+
+be_midi_interpolation = x
+ BeOS only: specifies the MIDI samples interpolation method. 0 doesn't
+ interpolate, it's fast but has the worst quality; 1 does a fast
+ interpolation with better performances, but it's a bit slower than the
+ previous method; 2 does a linear interpolation between samples, it is the
+ slowest method but gives the best performances.
+
+be_midi_reverb = x
+ BeOS only: reverberation intensity, from 0 to 5. 0 disables it, 5 is the
+ strongest one.
+
+ca_midi_quality = x
+ MacOS X only: CoreAudio MIDI synthesizer rendering quality, from 0 to 127.
+ Higher qualities sound better but increase the CPU work load.
+
+ca_midi_reverb = x
+ MacOS X only: CoreAudio MIDI synthesizer reverberation intensity, from 0
+ to 5. 0 equals to a small room (low reverb), 5 to a plate (high reverb).
+
+patches = x
+ Specifies where to find the sample set for the DIGMID driver. This can
+ either be a Gravis style directory containing a collection of .pat files
+ and a `default.cfg' index, or an Allegro datafile produced by the pat2dat
+ utility. If this variable is not set, Allegro will look either for a
+ `default.cfg' or `patches.dat' file in the same directory as the program,
+ the directory pointed to by the ALLEGRO environment variable, and the
+ standard GUS directory pointed to by the ULTRASND environment variable.
+
+[midimap]
+ If you are using the SB MIDI output or MPU-401 drivers with an external
+ synthesiser that is not General MIDI compatible, you can use the midimap
+ section of the config file to specify a patch mapping table for
+ converting GM patch numbers into whatever bank and program change
+ messages will select the appropriate sound on your synth. This is a real
+ piece of self-indulgence. I have a Yamaha TG500, which has some great
+ sounds but no GM patch set, and I just had to make it work somehow...
+
+ This section consists of a set of lines in the form:
+
+p<n> = bank0 bank1 prog pitch
+ With this statement, n is the GM program change number (1-128), bank0 and
+ bank1 are the two bank change messages to send to your synth (on
+ controllers #0 and #32), prog is the program change message to send to
+ your synth, and pitch is the number of semitones to shift everything that
+ is played with that sound. Setting the bank change numbers to -1 will
+ prevent them from being sent.
+
+ For example, the line:
+
+ p36 = 0 34 9 12
+
+ specifies that whenever GM program 36 (which happens to be a fretless
+ bass) is selected, Allegro should send a bank change message #0 with a
+ parameter of 0, a bank change message #32 with a parameter of 34, a
+ program change with a parameter of 9, and then should shift everything up
+ by an octave.
+
+[joystick]
+ Section containing joystick configuration information, using the
+ variables:
+
+joytype = x
+ Specifies which joystick driver to use when the program requests
+ JOY_TYPE_AUTODETECT.
+
+joystick_device = x
+ BeOS and Linux only: specifies the name of the joystick device to be used
+ (as reported in the system joystick preferences under BeOS). The first
+ device found is used by default. If you want to specify the device for
+ each joystick, use variables of the form joystick_device_n, where n is
+ the joystick number.
+
+throttle_axis = x
+ Linux only: sets the axis number the throttle is located at. This
+ variable will be used for every detected joystick. If you want to specify
+ the axis number for each joystick individually, use variables of the form
+ throttle_axis_n, where n is the joystick number.
+
show_mouse — Tells Allegro to display a mouse pointer on the screen.
+
show_os_cursor — Low level function to display the operating system cursor.
+
unscare_mouse — Undoes the effect of scare_mouse() or scare_mouse_area().
+
+
+
+Allegro provides functions for reading the mouse state and displaying a mouse
+cursor on-screen. You can read the absolute position of the mouse and the
+state of the mouse buttons from global variables. Additionally, you can read
+the mouse position difference as mouse mickeys, which is the number of pixels
+the cursor moved since the last time this information was read.
+
+
+Allegro offers three ways to display the mouse cursor:
+
+Standard Allegro cursor
+ Allegro is responsible for drawing the mouse cursor from a timer. Use
+ set_mouse_sprite() and show_mouse() to define your own cursor and display
+ it on the screen.
+ You need to call scare_mouse()/unscare_mouse() to hide the mouse cursor
+ whenever you draw to the screen.
+
+Custom operating system cursor (hardware cursor)
+ Allegro will let the operating system draw the mouse cursor. Use
+ set_mouse_sprite() and show_mouse() (or show_os_cursor) to define your
+ own cursor and display it on the screen. Not all graphics drivers are
+ capable of this and some may only be able to display cursors upto a
+ certain size. Allegro will fall back on its own cursor drawing if it
+ cannot let the OS handle this. On some platforms, the hardware cursor
+ is incompatible with get_mouse_mickeys() and it is therefor disabled by
+ default. In such cases you need to call enable_hardware_cursor() to
+ enable it explicitly.
+
+Default operating system cursor
+ Allegro will not draw its own cursor, but use the operating system default
+ cursor. You can use the select_mouse_cursor() function to select the cursor
+ shape to display. As with custom operating system cursors, you need to call
+ enable_hardware_cursor() before you can use this. Or you can use the
+ low level show_os_cursor() function.
+
+Not all drivers will support all functionality. See the platform specific
+information for more details.
+
+
+ Installs the Allegro mouse handler. You must do this before using any
+ other mouse functions.
+
Return value:
+ Returns -1 on failure, zero if the mouse handler is already installed (in
+ which case this function does nothing) and the number of buttons on the
+ mouse if the mouse handler has successfully been installed (ie. this is
+ the first time a handler is installed or you have removed the previous
+ one).
+
+
+ Note that the number of mouse buttons returned by this function is more
+ an indication than a physical reality. With most devices there is no way
+ of telling how many buttons there are, and any user can override the
+ number of mouse buttons returned by this function with a custom
+ configuration file and the variable num_buttons. Even if this value is
+ overriden by the user, the global mouse variables will still report
+ whatever the hardware is sending.
+
+
+
+ Wherever possible, Allegro will read the mouse input asynchronously (ie.
+ from inside an interrupt handler), but on some platforms that may not be
+ possible, in which case you must call this routine at regular intervals
+ to update the mouse state variables. To help you test your mouse polling
+ code even if you are programming on a platform that doesn't require it,
+ after the first time that you call this function Allegro will switch into
+ polling mode, so from that point onwards you will have to call this
+ routine in order to get any mouse input at all, regardless of whether the
+ current driver actually needs to be polled or not.
+
Return value:
+ Returns zero on success, or a negative number on failure (ie. no mouse
+ driver installed).
+
+
+
+ After calling this function, Allegro will let the operating system draw the
+ mouse cursor instead of doing it itself. This is not possible with all
+ graphics drivers though: you'll need to check the gfx_capabilities flags
+ after calling show_mouse() to see if this works. On some platforms, enabling
+ the hardware cursor causes get_mouse_mickeys() to return only a limited
+ range of values, so you should not call this function if you need mouse
+ mickeys.
+
+
+
+ After calling this function, Allegro will be responsible for drawing the
+ mouse cursor rather than the operating system. On some platforms calling
+ enable_hardware_cursor() makes the return values of get_mouse_mickeys()
+ unreliable. After calling this function, get_mouse_mickeys() returns
+ reliable results again.
+
+
+
+ This function allows you to use the operating system's native mouse
+ cursors rather than some custom cursor. You will need to enable this
+ functionality by calling enable_hardware_cursor() beforehand. If the
+ operating system does not support this functionality, or if it has
+ not been enabled, then Allegro will substitute its own cursor images.
+ You can change these substitute images using set_mouse_cursor_bitmap().
+
+
+ Note that the effects of this function are not apparent until show_mouse()
+ is called.
+
+
+ To know whether the operating system's native cursor is being used,
+ or if Allegro has made a substitution, you can check the GFX_SYSTEM_CURSOR
+ flag in gfx_capabilities after calling show_mouse().
+
+
+ The cursor argument selects the type of cursor to be displayed:
+
+
+ MOUSE_CURSOR_NONE
+ Selects an invisible mouse cursor. In that sense, it is similar to calling
+ show_mouse(NULL);
+
+
+ MOUSE_CURSOR_ALLEGRO
+ Selects the custom Allegro cursor, i.e. the one that you set with
+ set_mouse_sprite().
+
+
+ MOUSE_CURSOR_ARROW
+ The operating system default arrow cursor.
+
+
+ MOUSE_CURSOR_BUSY
+ The operating system default `busy' cursor (hourglass).
+
+
+ MOUSE_CURSOR_QUESTION
+ The operating system default `question' cursor (arrow with question mark).
+
+
+ MOUSE_CURSOR_EDIT
+ The operating system default `edit' cursor (vertical bar).
+
+
+ This function changes the cursor image Allegro uses if
+ select_mouse_cursor() is called but no native operating system cursor
+ can be used, e.g. because you did not call enable_hardware_cursor().
+
+
+ The cursor argument can be one of:
+ MOUSE_CURSOR_ALLEGRO
+ MOUSE_CURSOR_ARROW
+ MOUSE_CURSOR_BUSY
+ MOUSE_CURSOR_QUESTION
+ MOUSE_CURSOR_EDIT
+
+
+ but not MOUSE_CURSOR_NONE.
+
+
+ The bmp argument can either point to a valid bitmap or it can be NULL.
+ Passing a bitmap makes Allegro use that image in place of its own
+ default substition (should the operating system's native cursor
+ be unavailable). The bitmap must remain available for the duration
+ in which it could be used. Passing NULL lets Allegro revert to its
+ default substitutions.
+
+
+ The effect of this function will not be apparent until show_mouse() is
+ called.
+
+
+
+ Global variables containing the current mouse position and button state.
+ Wherever possible these values will be updated asynchronously, but if
+ mouse_needs_poll() returns TRUE, you must manually call poll_mouse() to
+ update them with the current input state. The `mouse_x' and `mouse_y'
+ positions are integers ranging from zero to the bottom right corner of
+ the screen. The `mouse_z' variable holds the current wheel position, when
+ using an input driver that supports wheel mice. The `mouse_b' variable is
+ a bitfield indicating the state of each button: bit 0 is the left button,
+ bit 1 the right, and bit 2 the middle button. Additional non standard
+ mouse buttons might be available as higher bits in this variable. Usage
+ example:
+
+ if (mouse_b & 1)
+ printf("Left button is pressed\n");
+
+ if (!(mouse_b & 2))
+ printf("Right button is not pressed\n");
+
+ The `mouse_pos' variable has the current X coordinate in the upper 16 bits
+ and the Y in the lower 16 bits. This may be useful in tight polling loops
+ where a mouse interrupt could occur between your reading of the two
+ separate variables, since you can copy this value into a local variable
+ with a single instruction and then split it up at your leisure. Example:
+
+ int pos, x, y;
+
+ pos = mouse_pos;
+ x = pos >> 16;
+ y = pos & 0x0000ffff;
+
+ Global variables containing the current mouse sprite and the focus
+ point. These are read-only, and only to be modified using the
+ set_mouse_sprite() and set_mouse_sprite_focus() functions.
+
+
+
+ Tells Allegro to display a mouse pointer on the screen. This will only
+ work if the timer module has been installed. The mouse pointer will be
+ drawn onto the specified bitmap, which should normally be `screen' (see
+ later for information about bitmaps). To hide the mouse pointer, call
+ show_mouse(NULL).
+
+
+ Warning: if you draw anything onto the screen while the pointer is
+ visible, a mouse movement interrupt could occur in the middle of your
+ drawing operation. If this happens the mouse buffering and graphics drawing
+ code will get confused and will leave 'mouse droppings' all over the
+ screen. To prevent this, you must make sure you turn off the mouse
+ pointer whenever you draw onto the screen. This is not needed if you are
+ using a hardware cursor.
+
+
+ Note: you must not be showing a mouse pointer on a bitmap at the time that
+ the bitmap is destroyed with destroy_bitmap(), e.g. call show_mouse(NULL);
+ before destroying the bitmap. This does not apply to `screen' since you
+ never destroy `screen' with destroy_bitmap().
+
+
+
+ Helper for hiding the mouse pointer prior to a drawing operation. This
+ will temporarily get rid of the pointer, but only if that is really
+ required (ie. the mouse is visible, and is displayed on the physical
+ screen rather than some other memory surface, and it is not a hardware
+ or OS cursor). The previous mouse state is stored for subsequent calls to
+ unscare_mouse().
+
+
+
+ Like scare_mouse(), but will only hide the cursor if it is inside the
+ specified rectangle. Otherwise the cursor will simply be frozen in place
+ until you call unscare_mouse(), so it cannot interfere with your drawing.
+
+
+
+ In case you do not need Allegro's mouse cursor API, which automatically
+ emulates a cursor in software if no other cursor is available, you can
+ use this low level function to try to display or hide the system cursor
+ directly. The cursor parameter takes the same values as
+ select_mouse_cursor. This function is very similar to calling
+ enable_hardware_cursor, select_mouse_cursor and show_mouse, but will
+ not try to do anything if no system cursor is available.
+
+
+ The most common use for this function is to just call it once at the
+ beginning of the program to tell it to display the system cursor inside
+ the Allegro window. The return value can be used to see if this
+ suceeded or not. On some systems (e.g. DirectX fullscreen) this is not
+ supported and the function will always fail, and in other cases only
+ some of the cursors will work, or in the case of MOUSE_CURSOR_ALLEGRO,
+ only certain bitmap sizes may be supported.
+
+
+ You never should use show_os_cursor together with the function
+ show_mouse and other functions affecting it (select_mouse_cursor,
+ enable_hardware_cursor, disable_hardware_cursor, scare_mouse,
+ unscare_mouse). They implement the standard high level mouse API, and
+ don't work together with this low level function.
+
Return value:
+ Returns 0 if a system cursor is being displayed after the function
+ returns, or -1 otherwise.
+
+
+
+ If this flag is set, the mouse pointer won't be redrawn when the mouse
+ moves. This can avoid the need to hide the pointer every time you draw to
+ the screen, as long as you make sure your drawing doesn't overlap with
+ the current pointer position.
+
+
+
+ Sets the area of the screen within which the mouse can move. Pass the top
+ left corner and the bottom right corner (inclusive). If you don't call
+ this function the range defaults to (0, 0, SCREEN_W-1, SCREEN_H-1).
+
+
+
+ You don't like Allegro's mouse pointer? No problem. Use this function to
+ supply an alternative of your own. If you change the pointer and then want
+ to get Allegro's lovely arrow back again, call set_mouse_sprite(NULL).
+
+
+ As a bonus, set_mouse_sprite(NULL) uses the current palette in choosing
+ colors for the arrow. So if your arrow mouse sprite looks ugly after
+ changing the palette, call set_mouse_sprite(NULL).
+
+
+
+ The mouse focus is the bit of the pointer that represents the actual
+ mouse position, ie. the (mouse_x, mouse_y) position. By default this is
+ the top left corner of the arrow, but if you are using a different mouse
+ pointer you might need to alter it.
+
+
+
+ Measures how far the mouse has moved since the last call to this
+ function. The values of mickeyx and mickeyy will become negative if the
+ mouse is moved left or up, respectively. The mouse will continue to
+ generate movement mickeys even when it reaches the edge of the screen, so
+ this form of input can be useful for games that require an infinite range
+ of mouse movement.
+
+
+ Note that the infinite movement may not work in windowed mode, since under
+ some platforms the mouse would leave the window, and may not work at all
+ if the hardware cursor is in use.
+
+
+
+ Called by the interrupt handler whenever the mouse moves or one of the
+ buttons changes state. This function must be in locked memory, and must
+ execute _very_ quickly! It is passed the event flags that triggered the
+ call, which is a bitmask containing any of the values MOUSE_FLAG_MOVE,
+ MOUSE_FLAG_LEFT_DOWN, MOUSE_FLAG_LEFT_UP, MOUSE_FLAG_RIGHT_DOWN,
+ MOUSE_FLAG_RIGHT_UP, MOUSE_FLAG_MIDDLE_DOWN, MOUSE_FLAG_MIDDLE_UP, and
+ MOUSE_FLAG_MOVE_Z. Note that even if the mouse has more than three buttons,
+ only the first three can be trapped using a callback.
+
+
+
+
+
+Allegro can set up several virtual timer functions, all going at different
+speeds.
+
+
+Under DOS it will constantly reprogram the clock to make sure they are all
+called at the correct times. Because they alter the low level timer chip
+settings, these routines should not be used together with other DOS timer
+functions like the DJGPP uclock() routine. Moreover, the FPU state is not
+preserved across Allegro interrupts so you ought not to use floating point
+or MMX code inside timer interrupt handlers.
+
+
+Under other platforms, they are usually implemented using threads, which run
+parallel to the main thread. Therefore timer callbacks on such platforms
+will not block the main thread when called, so you may need to use
+appropriate synchronisation devices (eg. mutexes, semaphores, etc.) when
+accessing data that is shared by a callback and the main thread. (Currently
+Allegro does not provide such devices.)
+
+
+ Installs the Allegro timer interrupt handler. You must do this before
+ installing any user timer routines, and also before displaying a mouse
+ pointer, playing FLI animations or MIDI music, and using any of the GUI
+ routines.
+
Return value:
+ Returns zero on success, or a negative number on failure (but you may
+ decide not to check the return value as this function is very unlikely to
+ fail).
+
+
+
+ Removes the Allegro timer handler (and, under DOS, passes control of the
+ clock back to the operating system). You don't normally need to bother
+ calling this, because allegro_exit() will do it for you.
+
+
+
+ Installs a user timer handler, with the speed given as the number of
+ milliseconds between ticks. This is the same thing as
+ install_int_ex(proc, MSEC_TO_TIMER(speed)). If you call this routine
+ without having first installed the timer module, install_timer() will be
+ called automatically. Calling again this routine with the same timer
+ handler as parameter allows you to adjust its speed.
+
Return value:
+ Returns zero on success, or a negative number if there is no room to add
+ a new user timer.
+
+
+
+ Adds a function to the list of user timer handlers or, if it is already
+ installed, retroactively adjusts its speed (i.e makes as though the speed
+ change occured precisely at the last tick). The speed is given in hardware
+ clock ticks, of which there are 1193181 a second. You can convert from
+ other time formats to hardware clock ticks with the macros:
+
+ SECS_TO_TIMER(secs) - give the number of seconds between
+ each tick
+ MSEC_TO_TIMER(msec) - give the number of milliseconds
+ between ticks
+ BPS_TO_TIMER(bps) - give the number of ticks each second
+ BPM_TO_TIMER(bpm) - give the number of ticks per minute
+
+ There can only be sixteen timers in use at a time, and some other parts of
+ Allegro (the GUI code, the mouse pointer display routines, rest(), the FLI
+ player, and the MIDI player) need to install handlers of their own, so you
+ should avoid using too many at the same time. If you call this routine
+ without having first installed the timer module, install_timer() will be
+ called automatically.
+
+
+ Your function will be called by the Allegro interrupt handler and not
+ directly by the processor, so it can be a normal C function and does not
+ need a special wrapper. You should be aware, however, that it will be
+ called in an interrupt context, which imposes a lot of restrictions on
+ what you can do in it. It should not use large amounts of stack, it must
+ not make any calls to the operating system, use C library functions, or
+ contain any floating point code, and it must execute very quickly. Don't
+ try to do lots of complicated code in a timer handler: as a general rule
+ you should just set some flags and respond to these later in your main
+ control loop.
+
+
+ In a DOS protected mode environment like DJGPP, memory is virtualised and
+ can be swapped to disk. Due to the non-reentrancy of DOS, if a disk swap
+ occurs inside an interrupt handler the system will die a painful death,
+ so you need to make sure you lock all the memory (both code and data)
+ that is touched inside timer routines. Allegro will lock everything it
+ uses, but you are responsible for locking your handler functions. The
+ macros LOCK_VARIABLE (variable), END_OF_FUNCTION (function_name),
+ END_OF_STATIC_FUNCTION (function_name), and LOCK_FUNCTION (function_name)
+ can be used to simplify this task. For example, if you want an interrupt
+ handler that increments a counter variable, you should write:
+
+ Obviously this can get awkward if you use complicated data structures and
+ call other functions from within your handler, so you should try to keep
+ your interrupt routines as simple as possible.
+
Return value:
+ Returns zero on success, or a negative number if there is no room to add
+ a new user timer.
+
+
+
+ Due to interrupts, you are required to lock all the memory used by your
+ timer routines. See the description of install_int_ex() for a more
+ detailed explanation and usage example.
+
+
+
+ Due to interrupts, you are required to lock all the memory used by your
+ timer routines. See the description of install_int_ex() for a more
+ detailed explanation and usage example.
+
+
+
+ Due to interrupts, you are required to lock all the code used by your
+ timer routines. See the description of install_int_ex() for a more
+ detailed explanation and usage example.
+
+
+
int install_param_int(void (*proc)(void *), void *param, int speed);
+ Like install_int(), but the callback routine will be passed a copy of the
+ specified void pointer parameter. To disable the handler, use
+ remove_param_int() instead of remove_int().
+
+
+
+ Like install_int_ex(), but the callback routine will be passed a copy of
+ the specified void pointer parameter. To disable the handler, use
+ remove_param_int() instead of remove_int().
+
+
+
+ Like remove_int(), but for use with timer callbacks that have parameter
+ values. If there is more than one copy of the same callback active at a
+ time, it identifies which one to remove by checking the parameter value
+ (so you can't have more than one copy of a handler using an identical
+ parameter).
+
+
+
+ If the retrace simulator is installed, this count is incremented on each
+ vertical retrace; otherwise, if the refresh rate is known, the count is
+ incremented at the same rate (ignoring retraces); otherwise, it is
+ incremented 70 times a second. This provides a way of controlling
+ the speed of your program without installing user timer functions.
+
+
+
+ This function waits for the specified number of milliseconds.
+
+
+ Passing 0 as parameter will not wait, but just yield. This can be useful
+ in order to "play nice" with other processes. Other values will cause
+ CPU time to be dropped on most platforms. This will look better to
+ users, and also does things like saving battery power and making fans
+ less noisy.
+
+
+ Note that calling this inside your active game loop is a bad idea, as
+ you never know when the OS will give you the CPU back, so you could end
+ up missing the vertical retrace and skipping frames. On the other hand,
+ on multitasking operating systems it is good form to give up the CPU for
+ a while if you will not be using it.
+
+
+
+ Like rest(), but for non-zero values continually calls the specified
+ function while it is waiting for the required time to elapse. If the
+ provided `callback' parameter is NULL, this function does exactly the
+ same thing as calling rest().
+
+
+
+
+
three_finger_flag — Flag to desactivate the emergency exit key combination.
+
ureadkey — Returns the next unicode character from the keyboard buffer.
+
+
+
+The Allegro keyboard handler provides both buffered input and a set of flags
+storing the current state of each key. Note that it is not possible to
+correctly detect every combination of keys, due to the design of the PC
+keyboard. Up to two or three keys at a time will work fine, but if you press
+more than that the extras are likely to be ignored (exactly which
+combinations are possible seems to vary from one keyboard to another).
+
+
+On DOS, Allegro requires the user to specify the language of the keyboard
+mapping because it is impossible to obtain this information from the OS,
+otherwise the default US keyboard mapping will be used. Allegro comes with a
+prepackaged `keyboard.dat' file which you can put along with your binary. If
+this file is present, Allegro will be able to extract the keyboard mapping
+information stored there. However, the end user still needs to select which
+keyboard mapping to use. This can be acomplished through the keyboard variable
+of the system section in a standard `allegro.cfg' configuration file. Read
+chapter "Configuration routines" for more information about this.
+
+
+ Installs the Allegro keyboard interrupt handler. You must call this
+ before using any of the keyboard input routines. Once you have set up the
+ Allegro handler, you can no longer use operating system calls or C
+ library functions to access the keyboard.
+
+
+ Note that on some platforms the keyboard won't work unless you have set a
+ graphics mode, even if this function returns a success value before
+ calling set_gfx_mode. This can happen in environments with graphic
+ windowed modes, since Allegro usually reads the keyboard through the
+ graphical window (which appears after the set_gfx_call). Example:
+
+ allegro_init();
+ install_timer();
+ install_keyboard();
+ /* We are not 100% sure we can read the keyboard yet! */
+ if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0)
+ abort_on_error("Couldn't set graphic mode!")
+
+ /* Now we are guaranteed to be able to read the keyboard. */
+ readkey();
+
Return value:
+ Returns zero on success, or a negative number on failure (but you may
+ decide not to check the return value as this function is very unlikely to
+ fail).
+
+
+
+ Removes the keyboard handler, returning control to the operating system.
+ You don't normally need to bother calling this, because allegro_exit()
+ will do it for you. However, you might want to call this during runtime if
+ you want to change the keyboard mapping on those platforms were keyboard
+ mappings are needed. You would first modify the configuration variable
+ holding the keyboard mapping and then reinstall the keyboard handler.
+ Example:
+
+ You should only use this function if you *aren't* using the rest of the
+ keyboard handler. It should be called in the place of install_keyboard(),
+ and lets you provide callback routines to detect and read keypresses,
+ which will be used by the main keypressed() and readkey() functions. This
+ can be useful if you want to use Allegro's GUI code with a custom
+ keyboard handler, as it provides a way for the GUI to get keyboard input
+ from your own code, bypassing the normal Allegro input system.
+
+
+
+ Wherever possible, Allegro will read the keyboard input asynchronously
+ (ie. from inside an interrupt handler), but on some platforms that may
+ not be possible, in which case you must call this routine at regular
+ intervals to update the keyboard state variables.
+
+
+ To help you test your keyboard polling code even if you are programming
+ on a platform that doesn't require it, after the first time that you
+ call this function Allegro will switch into polling mode, so from that
+ point onwards you will have to call this routine in order to get any
+ keyboard input at all, regardless of whether the current driver actually
+ needs to be polled or not.
+
+
+ The keypressed(), readkey(), and ureadkey() functions call poll_keyboard()
+ automatically, so you only need to use this function when accessing the
+ key[] array and key_shifts variable.
+
Return value:
+ Returns zero on success, or a negative number on failure (ie. no keyboard
+ driver installed).
+
+
+
+ Array of flags indicating the state of each key, ordered by scancode.
+ Wherever possible these values will be updated asynchronously, but if
+ keyboard_needs_poll() returns TRUE, you must manually call
+ poll_keyboard() to update them with the current input state. The
+ scancodes are defined in allegro/keyboard.h as a series of KEY_*
+ constants (and are also listed below). For example, you could write:
+
+ if (key[KEY_SPACE])
+ printf("Space is pressed\n");
+
+
+ Note that the array is supposed to represent which keys are physically
+ held down and which keys are not, so it is semantically read-only.
+
+
+ Finally, you may notice an `odd' behaviour of the KEY_PAUSE key. This key
+ only generates an interrupt when it is pressed, not when it is released.
+ For this reason, Allegro pretends the pause key is a `state' key, which
+ is the only way to make it usable.
+
+
+
+ Bitmask containing the current state of shift/ctrl/alt, the special
+ Windows keys, and the accent escape characters. Wherever possible this
+ value will be updated asynchronously, but if keyboard_needs_poll()
+ returns TRUE, you must manually call poll_keyboard() to update it with
+ the current input state. This can contain any of the flags:
+
+ Returns TRUE if there are keypresses waiting in the input buffer. You can
+ use this to see if the next call to readkey() is going to block or to
+ simply wait for the user to press a key while you still update the screen
+ possibly drawing some animation. Example:
+
+ while (!keypressed()) {
+ /* Show cool animated logo. */
+ }
+ /* So he skipped our title screen. */
+ Returns the next character from the keyboard buffer, in ASCII format. If
+ the buffer is empty, it waits until a key is pressed. You can see if there
+ are queued keypresses with keypressed().
+
+
+ The low byte of the return value contains the ASCII code of the key, and
+ the high byte the scancode. The scancode remains the same whatever the
+ state of the shift, ctrl and alt keys, while the ASCII code is affected by
+ shift and ctrl in the normal way (shift changes case, ctrl+letter gives
+ the position of that letter in the alphabet, eg. ctrl+A = 1, ctrl+B = 2,
+ etc). Pressing alt+key returns only the scancode, with a zero ASCII code
+ in the low byte. For example:
+
+ int val;
+ ...
+ val = readkey();
+ if ((val & 0xff) == 'd') /* by ASCII code */
+ allegro_message("You pressed 'd'\n");
+
+ if ((val >> 8) == KEY_SPACE) /* by scancode */
+ allegro_message("You pressed Space\n");
+
+ if ((val & 0xff) == 3) /* ctrl+letter */
+ allegro_message("You pressed Control+C\n");
+
+ if (val == (KEY_X << 8)) /* alt+letter */
+ allegro_message("You pressed Alt+X\n");
+
+ This function cannot return character values greater than 255. If you
+ need to read Unicode input, use ureadkey() instead.
+
+
+
+ Returns the next character from the keyboard buffer, in Unicode format.
+ If the buffer is empty, it waits until a key is pressed. You can see if
+ there are queued keypresses with keypressed(). The return value contains
+ the Unicode value of the key, and if not NULL, the pointer argument will
+ be set to the scancode. Unlike readkey(), this function is able to return
+ character values greater than 255. Example:
+
+ int val, scancode;
+ ...
+ val = ureadkey(&scancode);
+ if (val == 0x00F1)
+ allegro_message("You pressed n with tilde\n");
+
+ if (val == 0x00DF)
+ allegro_message("You pressed sharp s\n");
+
+ You should be able to find Unicode character maps at
+ http://www.unicode.org/. Remember that on DOS you must specify a custom
+ keyboard map (like those found in `keyboard.dat') usually with the help of
+ a configuration file specifying the language mapping (keyboard variable in
+ system section of `allegro.cfg'), or you will get the default US keyboard
+ mapping.
+
+
+
+ Converts the given scancode to an ASCII character for that key (mangling
+ Unicode values), returning the unshifted uncapslocked result of pressing
+ the key, or zero if the key isn't a character-generating key or the lookup
+ can't be done. The lookup cannot be done for keys like the F1-F12 keys or the
+ cursor keys, and some drivers will only return approximate values. Generally,
+ if you want to display the name of a key to the user, you should use the
+ scancode_to_name function.
+
+
+ This function returns a string pointer containing the name of they key with
+ the given scancode. This is useful if you e.g. let the user choose a key for
+ some action, and want to display something more meaningful than just the
+ scancode. Example:
+
+ If set, this function is called by the keyboard handler in response to
+ every keypress. It is passed a copy of the value that is about to be
+ added into the input buffer, and can either return this value unchanged,
+ return zero to cause the key to be ignored, or return a modified value to
+ change what readkey() will later return. This routine executes in an
+ interrupt context, so it must be in locked memory. Example:
+
+ Unicode-aware version of keyboard_callback(). If set, this function is
+ called by the keyboard handler in response to every keypress. It is
+ passed the character value and scancode that are about to be added into
+ the input buffer, can modify the scancode value, and returns a new or
+ modified key code. If it both sets the scancode to zero and returns zero,
+ the keypress will be ignored. This routine executes in an interrupt
+ context, so it must be in locked memory. Example:
+
+ If set, this function is called by the keyboard handler in response to
+ every keyboard event, both presses (including keyboard repeat rate) and
+ releases. It will be passed a raw keyboard scancode byte (scancodes are
+ 7 bits long), with the top bit (8th bit) clear if the key has been
+ pressed or set if it was released. This routine executes in an interrupt
+ context, so it must be in locked memory. Example:
+
+ Overrides the state of the keyboard LED indicators. The parameter is a
+ bitmask containing any of the values KB_SCROLOCK_FLAG, KB_NUMLOCK_FLAG,
+ and KB_CAPSLOCK_FLAG, or -1 to restore the default behavior. Example:
+
+ Note that the led behaviour cannot be guaranteed on some platforms, some
+ leds might not react, or none at all. Therefore you shouldn't rely only on
+ them to communicate information to the user, just in case it doesn't get
+ through.
+
+
+
+ Empties the keyboard buffer. Usually you want to use this in your program
+ before reading keys to avoid previously buffered keys to be returned by
+ calls to readkey() or ureadkey().
+
+
+
+ The DJGPP keyboard handler provides an 'emergency exit' sequence which
+ you can use to kill off your program. If you are running under DOS this
+ is the three finger salute, ctrl+alt+del. Most multitasking OS's will
+ trap this combination before it reaches the Allegro handler, in which
+ case you can use the alternative ctrl+alt+end. If you want to disable
+ this behaviour in release versions of your program, set this flag to
+ FALSE.
+
+
+
+ By default, the capslock, numlock, and scroll-lock keys toggle the
+ keyboard LED indicators when they are pressed. If you are using these
+ keys for input in your game (eg. capslock to fire) this may not be
+ desirable, so you can clear this flag to prevent the LED's being updated.
+
+
+
+
+
+Unlike keyboard or mouse input, which are usually read through hardware
+interrupts by Allegro, joystick input functions have to be polled because
+there are no hardware interrupts for them on most platforms. This doesn't
+mean that you have to poll the joysticks on each line of code you want to
+read their values, but you should make sure to poll them at least once per
+frame in your game loop. Otherwise you face the possibility of reading stale
+incorrect data.
+
+
+ Installs Allegro's joystick handler, and calibrates the centre position
+ values. The type parameter should usually be JOY_TYPE_AUTODETECT, or see
+ the platform specific documentation for a list of the available drivers.
+ You must call this routine before using any other joystick functions, and
+ you should make sure that all joysticks are in the middle position at the
+ time. Example:
+
Return value:
+ Returns zero on success. As soon as you have installed the joystick
+ module, you will be able to read the button state and digital (on/off
+ toggle) direction information, which may be enough for some games. If you
+ want to get full analogue input, though, you need to use the
+ calibrate_joystick() functions to measure the exact range of the inputs:
+ see below.
+
+
+
+ The joystick handler is not interrupt driven, so you need to call this
+ function every now and again to update the global position values. Example:
+
+ do {
+ /* Get joystick input */
+ poll_joystick();
+
+ /* Process input for the first joystick */
+ if (joy[0].button[0].b)
+ first_button_pressed();
+
+ if (joy[0].button[1].b)
+ second_button_pressed();
+ ...
+ } while(!done);
+
Return value:
+ Returns zero on success or a negative number on failure (usually because
+ no joystick driver was installed).
+
+
+
+ Global array of joystick state information, which is updated by the
+ poll_joystick() function. Only the first num_joysticks elements will
+ contain meaningful information. The JOYSTICK_INFO structure is defined as:
+
+ typedef struct JOYSTICK_INFO
+ {
+ int flags; - status flags for this
+ joystick
+ int num_sticks; - how many stick inputs?
+ int num_buttons; - how many buttons?
+ JOYSTICK_STICK_INFO stick[n]; - stick state information
+ JOYSTICK_BUTTON_INFO button[n]; - button state information
+ } JOYSTICK_INFO;
+
+ You may wish to display the button names as part of an input
+ configuration screen to let the user choose what game function will be
+ performed by each button, but in simpler situations you can safely assume
+ that the first two elements in the button array will always be the main
+ trigger controls.
+
+
+ Each joystick will provide one or more stick inputs, of varying types.
+ These can be digital controls which snap to specific positions (eg. a
+ gamepad controller, the coolie hat on a Flightstick Pro or Wingman
+ Extreme, or a normal joystick which hasn't yet been calibrated), or they
+ can be full analogue inputs with a smooth range of motion. Sticks may
+ also have different numbers of axes, for example a normal directional
+ control has two, but the Flightstick Pro throttle is only a single axis,
+ and it is possible that the system could be extended in the future to
+ support full 3d controllers. A stick input is described by the structure:
+
+ typedef struct JOYSTICK_STICK_INFO
+ {
+ int flags; - status flags for this
+ input
+ int num_axis; - how many axes do we
+ have? (note the misspelling)
+ JOYSTICK_AXIS_INFO axis[n]; - axis state information
+ char *name; - description of this
+ input
+ } JOYSTICK_STICK_INFO;
+
+ A single joystick may provide several different stick inputs, but you can
+ safely assume that the first element in the stick array will always be
+ the main directional controller.
+
+
+ Information about each of the stick axis is stored in the substructure:
+
+ typedef struct JOYSTICK_AXIS_INFO
+ {
+ int pos; - analogue axis position
+ int d1, d2; - digital axis position
+ char *name; - description of this axis
+ } JOYSTICK_AXIS_INFO;
+
+ This provides both analogue input in the pos field (ranging from -128 to
+ 128 or from 0 to 255, depending on the type of the control), and digital
+ values in the d1 and d2 fields. For example, when describing the X-axis
+ position, the pos field will hold the horizontal position of the
+ joystick, d1 will be set if it is moved left, and d2 will be set if it is
+ moved right. Allegro will fill in all these values regardless of whether
+ it is using a digital or analogue joystick, emulating the pos field for
+ digital inputs by snapping it to the min, middle, and maximum positions,
+ and emulating the d1 and d2 values for an analogue stick by comparing the
+ current position with the centre point.
+
+
+ The joystick flags field may contain any combination of the bit flags:
+
+
+ JOYFLAG_DIGITAL
+ This control is currently providing digital input.
+
+
+ JOYFLAG_ANALOGUE
+ This control is currently providing analogue input.
+
+
+ JOYFLAG_CALIB_DIGITAL
+ This control will be capable of providing digital input once it has
+ been calibrated, but is not doing this at the moment.
+
+
+ JOYFLAG_CALIB_ANALOGUE
+ This control will be capable of providing analogue input once it has
+ been calibrated, but is not doing this at the moment.
+
+
+ JOYFLAG_CALIBRATE
+ Indicates that this control needs to be calibrated. Many devices
+ require multiple calibration steps, so you should call the
+ calibrate_joystick() function from a loop until this flag is cleared.
+
+
+ JOYFLAG_SIGNED
+ Indicates that the analogue axis position is in signed format, ranging
+ from -128 to 128. This is the case for all 2d directional controls.
+
+
+ JOYFLAG_UNSIGNED
+ Indicates that the analogue axis position is in unsigned format,
+ ranging from 0 to 255. This is the case for all 1d throttle controls.
+
+
+ Note for people who spell funny: in case you don't like having to type
+ "analogue", there are some #define aliases in allegro/joystick.h that
+ will allow you to write "analog" instead.
+
+
+
+ Pass the number of the joystick you want to calibrate as the parameter.
+
Return value:
+ Returns a text description for the next type of calibration that will be
+ done on the specified joystick, or NULL if no more calibration is
+ required.
+
+
+
+ Most joysticks need to be calibrated before they can provide full
+ analogue input. This function performs the next operation in the
+ calibration series for the specified stick, assuming that the joystick
+ has been positioned in the manner described by a previous call to
+ calibrate_joystick_name(), returning zero on success. For example, a
+ simple routine to fully calibrate all the joysticks might look like:
+
+ After all the headache of calibrating the joystick, you may not want to
+ make your poor users repeat the process every time they run your program.
+ Call this function to save the joystick calibration data into the
+ specified configuration file, from which it can later be read by
+ load_joystick_data(). Pass a NULL filename to write the data to the
+ currently selected configuration file.
+
Return value:
+ Returns zero on success, non-zero if the data could not be saved.
+
+
+
+ Restores calibration data previously stored by save_joystick_data() or
+ the setup utility. This sets up all aspects of the joystick code: you
+ don't even need to call install_joystick() if you are using this
+ function. Pass a NULL filename to read the data from the currently
+ selected configuration file.
+
Return value:
+ Returns zero on success: if it fails the joystick state is undefined and
+ you must reinitialise it from scratch.
+
+
+
+Graphics modes are the common denominator for most Allegro programs. While it
+is possible to write platform specific programs using Allegro which don't set
+a graphic mode through the routines provided in this chapter, these are not
+very common.
+
+
+The first thing to note is that due to the wide range of supported platforms,
+a graphic mode is the only way to safely communicate with the user. When
+Allegro was a DOS only library (versions 3.x and previous), it was frequent
+for programmers to use functions from the C standard library to communicate
+with the user, like calling printf() before setting a graphic mode or maybe
+scanf() to read the user's input. However, what would happen for such a game
+running under Windows where there is no default console output or it may be
+hidden from the user? Even if the game compiled successfully, it would be
+unplayable, especially if there was vital information for the user in those
+text only messages.
+
+
+Allegro provides the allegro_message() function to deal with this problem,
+but this is not a very user friendly method of communicating with the user
+and its main purpose is displaying small error like messages when no graphic
+mode is available. Therefore, the first thing your Allegro program should do
+is set a graphic mode, and from there on, use Allegro's text output routines
+to display messages to the user, just like `allegro/examples/exhello.c' does.
+
+
+Setting a graphic mode involves deciding how to allocate the memory of the
+video card for your program. On some platforms this means creating a virtual
+screen bigger than the physical resolution to do hardware scrolling or page
+flipping. Virtual screens can cause a lot of confusion, but they are really
+quite simple. Warning: patronising explanation coming up, so you may wish to
+skip the rest of this paragraph. Think of video memory as a rectangular piece
+of paper which is being viewed through a small hole (your monitor) in a bit of
+cardboard. Since the paper is bigger than the hole you can only see part of it
+at any one time, but by sliding the cardboard around you can alter which
+portion of the image is visible. You could just leave the hole in one position
+and ignore the parts of video memory that aren't visible, but you can get all
+sorts of useful effects by sliding the screen window around, or by drawing
+images in a hidden part of video memory and then flipping across to display
+them.
+
+
+For example, you could select a 640x480 mode in which the monitor acts as a
+window onto a 1024x1024 virtual screen, and then move the visible screen
+around in this larger area (hardware scrolling). Initially, with the visible
+screen positioned at the top left corner of video memory, this setup would
+look like:
+
+With a virtual screen bigger than the visible screen you can perform smooth
+CPU inexpensive scrolling: you draw your graphics once, and then only tell
+the video card to show a different portion of the screen. However, virtual
+screens are not supported on all platforms, and on some they might be
+emulated through software, losing any performance. On top of that, many video
+cards only allow horizontal scrolling in steps of 32 bytes. This is not a
+problem if your game runs in 24 or 32 bit, but it tends to mean jerky
+scrolling for other color depths.
+
+
+The other reason you could use virtual screens for is page flipping. This
+means showing one portion of the virtual screen while your program draws to
+the hidden one. When you finish, you show the part you have been drawing to
+and repeat the process with the area now hidden. The result is a perfectly
+smooth screen update without flickering or other graphical artifacts.
+
+
+Scrolling manually to one part of the video memory is one non portable way to
+accomplish this. The portable way is to use functions like
+create_system_bitmap(), create_video_bitmap(), show_video_bitmap(), etc. These
+functions divide the memory of the video card in areas and switch between
+them, a feature supported on all platforms and video cards (given that they
+have enough memory for the screen resolutions you asked for).
+
+
+The last thing you need to know about setting a graphic mode are drivers.
+Each platform has a number of graphic drivers wich support a different range
+of hardware or behave in different ways. To avoid cluttering your own code
+with #ifdefs and dealing with drivers added after you release your program,
+Allegro provides several so called magic drivers. These magic drivers don't
+really exists, they wrap around a specific kind of functionality.
+
+
+The magic drivers you can use are:
+
+GFX_AUTODETECT:
+ Allegro will try to set the specified resolution with the current color
+ depth in fullscreen mode. Failing that, it will try to repeat the same
+ operation in windowed mode. If the call to set_gfx_mode() succeeds, you
+ are guaranteed to have set the specified resolution in the current color
+ depth, but you don't know if the program is running fullscreen or
+ windowed.
+
+GFX_AUTODETECT_FULLSCREEN:
+ Allegro will try to set the specified resolution with the current color
+ depth in fullscreen mode. If that is not possible, set_gfx_mode() will
+ fail.
+
+GFX_AUTODETECT_WINDOWED:
+ Allegro will try to set the specified resolution with the current color
+ depth in a windowed mode. If that is not possible, set_gfx_mode() will
+ fail. When it comes to windowed modes, the `specified resolution' actually
+ means the graphic area your program can draw on, without including window
+ decorations (if any). Note that in windowed modes running with a color
+ depth other than the desktop may result in non optimal performance due to
+ internal color conversions in the graphic driver. Use
+ desktop_color_depth() to your advantage in these situations.
+
+GFX_SAFE:
+ Using this driver Allegro guarantees that a graphic mode will always be
+ set correctly. It will try to select the resolution that you request, and
+ if that fails, it will fall back upon whatever mode is known to be
+ reliable on the current platform (this is 320x200 VGA mode under DOS, a
+ 640x480 resolution under Windows, the actual framebuffer's resolution
+ under Linux if it's supported, etc). If it absolutely cannot set any
+ graphics mode at all, it will return negative as usual, meaning that
+ there's no possible video output on the machine, and that you should abort
+ your program immediately, possibly after notifying this to the user with
+ allegro_message.
+
+ This fake driver is useful for situations where you just want to get into
+ some kind of workable display mode, and can't be bothered with trying
+ multiple different resolutions and doing all the error checking yourself.
+ Note however, that after a successful call to set_gfx_mode with this
+ driver, you cannot make any assumptions about the width, height or color
+ depth of the screen: your code will have to deal with this little detail.
+
+ GFX_TEXT:
+ Closes any previously opened graphics mode, making you unable to use the
+ global variable `screen', and in those environments that have text modes,
+ sets one previously used or the closest match to that (usually 80x25).
+ With this driver the size parameters of set_gfx_mode don't mean anything,
+ so you can leave them all to zero or any other number you prefer.
+
+ Sets the pixel format to be used by subsequent calls to set_gfx_mode()
+ and create_bitmap(). Valid depths are 8 (the default), 15, 16, 24, and 32
+ bits. Example:
+
+ set_color_depth(32);
+ if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0) {
+ abort_on_error("Couldn't set a 32 bit color resolution");
+ }
+
+ Note that the screen color depth won't change until the next successful
+ call to set_gfx_mode().
+
+
+
+ Returns the current pixel format. This can be very useful to know in order
+ to write generic functions which select a different code path internally
+ depending on the color depth being used.
+
+
+ Note that the function returns whatever value you may have set previously
+ with set_color_depth(), which can be different from the current color
+ depth of the screen global variable. If you really need to know the color
+ depth of the screen, use bitmap_color_depth().
+
+
+
+ Requests that the next call to set_gfx_mode() try to use the specified
+ refresh rate, if possible. Not all drivers are able to control this at
+ all, and even when they can, not all rates will be possible on all
+ hardware, so the actual settings may differ from what you requested.
+ After you call set_gfx_mode(), you can use get_refresh_rate() to find out
+ what was actually selected. At the moment only the DOS VESA 3.0, X DGA 2.0
+ and some Windows DirectX drivers support this function. The speed is
+ specified in Hz, eg. 60, 70. To return to the normal default selection,
+ pass a rate value of zero. Example:
+
+ request_refresh_rate(60);
+ if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0)
+ abort_on_error("Couldn't set graphic mode!");
+ if (get_refresh_rate() != 60)
+ abort_on_error("Couldn't set refresh rate to 60Hz!");
+ Returns the current refresh rate, if known (not all drivers are able to
+ report this information). Returns zero if the actual rate is unknown.
+
+
+
+ Attempts to create a list of all the supported video modes for a certain
+ graphics driver, made up from the GFX_MODE_LIST structure, which has the
+ following definition:
+
+ This list of video modes is terminated with an { 0, 0, 0 } entry.
+
+
+ Note that the card parameter must refer to a _real_ driver. This function
+ fails if you pass GFX_SAFE, GFX_AUTODETECT, or any other "magic" driver.
+
Return value:
+ Returns a pointer to a list structure of the type GFX_MODE_LIST or NULL
+ if the request could not be satisfied.
+
+
+
+ Removes the mode list created by get_gfx_mode_list() from memory. Use this
+ once you are done with the generated mode list to avoid memory leaks in
+ your program.
+
+
+
int set_gfx_mode(int card, int w, int h, int v_w, int v_h);
+ Switches into graphics mode. The card parameter should usually be one of
+ the Allegro magic drivers (read introduction of chapter "Graphics modes")
+ or see the platform specific documentation for a list of the available
+ drivers. The w and h parameters specify what screen resolution you want.
+ The color depth of the graphic mode has to be specified before calling
+ this function with set_color_depth().
+
+
+ The v_w and v_h parameters specify the minimum virtual screen size, in
+ case you need a large virtual screen for hardware scrolling or page
+ flipping. You should set them to zero if you don't care about the virtual
+ screen size.
+
+
+ When you call set_gfx_mode(), the v_w and v_h parameters represent the
+ minimum size of virtual screen that is acceptable for your program. The
+ range of possible sizes is usually very restricted, and Allegro may
+ end up creating a virtual screen much larger than the one you request.
+ Allowed sizes are driver dependent and some drivers do not allow virtual
+ screens that are larger than the visible screen at all: don't assume
+ that whatever you pass will always work.
+
+
+ In mode-X the virtual width can be any multiple of eight greater than or
+ equal to the physical screen width, and the virtual height will be set
+ accordingly (the VGA has 256k of vram, so the virtual height will be
+ 256*1024/virtual_width).
+
+
+ Currently, using a big virtual screen for page flipping is considered bad
+ practice. There are platforms which don't support virtual screens bigger
+ than the physical screen but can create different video pages to flip back
+ and forth. This means that, if you want page flipping and aren't going to
+ use hardware scrolling, you should call set_gfx_mode() with (0,0) as the
+ virtual screen size and later create the different video pages with
+ create_video_bitmap(). Otherwise your program will be limited to the
+ platforms supporting hardware scrolling.
+
+
+ After you select a graphics mode, the physical and virtual screen sizes
+ can be checked with the macros SCREEN_W, SCREEN_H, VIRTUAL_W, and
+ VIRTUAL_H.
+
Return value:
+ Returns zero on success. On failure returns a negative number and stores a
+ description of the problem in allegro_error.
+
+
+
+ Sets how the program should handle being switched into the background,
+ if the user tabs away from it. Not all of the possible modes will be
+ supported by every graphics driver on every platform. The available modes
+ are:
+
+ SWITCH_NONE
+ Disables switching. This is the default in single-tasking systems like
+ DOS. It may be supported on other platforms, but you should use it
+ with caution, because your users won't be impressed if they want to
+ switch away from your program, but you don't let them!
+
+ SWITCH_PAUSE
+ Pauses the program whenever it is in the background. Execution will be
+ resumed as soon as the user switches back to it. This is the default
+ in most fullscreen multitasking environments, for example the Linux
+ console, but not under Windows.
+
+ SWITCH_AMNESIA
+ Like SWITCH_PAUSE, but this mode doesn't bother to remember the
+ contents of video memory, so the screen, and any video bitmaps that
+ you have created, will be erased after the user switches away and then
+ back to your program. This is not a terribly useful mode to have, but
+ it is the default for the fullscreen drivers under Windows because
+ DirectDraw is too dumb to implement anything better.
+
+ SWITCH_BACKGROUND
+ The program will carry on running in the background, with the screen
+ bitmap temporarily being pointed at a memory buffer for the fullscreen
+ drivers. You must take special care when using this mode, because bad
+ things will happen if the screen bitmap gets changed around when your
+ program isn't expecting it (see below).
+
+ SWITCH_BACKAMNESIA
+ Like SWITCH_BACKGROUND, but this mode doesn't bother to remember the
+ contents of video memory (see SWITCH_AMNESIA). It is again the only
+ mode supported by the fullscreen drivers under Windows that lets the
+ program keep running in the background.
+
+ Note that you should be very careful when you are using graphics routines
+ in the switching context: you must always call acquire_screen() before the
+ start of any drawing code onto the screen and not release it until you are
+ completely finished, because the automatic locking mechanism may not be
+ good enough to work when the program runs in the background or has just
+ been raised in the foreground.
+
Return value:
+ Returns zero on success, invalidating at the same time all callbacks
+ previously registered with set_display_switch_callback(). Returns -1 if
+ the requested mode is not currently possible.
+
+
+
+ Installs a notification callback for the switching mode that was
+ previously selected by calling set_display_switch_mode(). The direction
+ parameter can either be SWITCH_IN or SWITCH_OUT, depending whether you
+ want to be notified about switches away from your program or back to your
+ program. You can sometimes install callbacks for both directions at the
+ same time, but not every platform supports this. You can install several
+ switch callbacks, but no more than eight on any platform.
+
Return value:
+ Returns zero on success, decreasing the number of empty callback slots by
+ one. Returns -1 if the request is impossible for the current platform or
+ you have reached the maximum number of allowed callbacks.
+
+
+
+ Removes a notification callback that was previously installed by calling
+ set_display_switch_callback(). All the callbacks will automatically be
+ removed when you call set_display_switch_mode(). You can safely call this
+ function even if the callback you want to remove is not installed.
+
+
+
Return value:
+ Returns true if the current graphics mode is a windowed mode, or zero if
+ it is a fullscreen mode. You should not call this function if you are not
+ in graphics mode.
+
+
+
+ Bitfield describing the capabilities of the current graphics driver and
+ video hardware. This may contain combination any of the flags:
+
+
+ GFX_CAN_SCROLL:
+ Indicates that the scroll_screen() function may be used with this
+ driver.
+
+
+ GFX_CAN_TRIPLE_BUFFER:
+ Indicates that the request_scroll() and poll_scroll() functions may be
+ used with this driver. If this flag is not set, it is possible that
+ the enable_triple_buffer() function may be able to activate it.
+
+
+ GFX_HW_CURSOR:
+ Indicates that a hardware mouse cursor is in use. When this flag is
+ set, it is safe to draw onto the screen without hiding the mouse
+ pointer first. Note that not every cursor graphic can be implemented
+ in hardware: in particular VBE/AF only supports 2-color images up to
+ 32x32 in size, where the second color is an exact inverse of the
+ first. This means that Allegro may need to switch between hardware and
+ software cursors at any point during the execution of your program, so
+ you should not assume that this flag will remain constant for long
+ periods of time. It only tells you whether a hardware cursor is in use
+ at the current time, and may change whenever you hide/redisplay the
+ pointer.
+
+
+ GFX_SYSTEM_CURSOR
+ Indicates that the mouse cursor is the default system cursor, not
+ Allegro's custom cursor.
+
+
+ GFX_HW_HLINE:
+ Indicates that the normal opaque version of the hline() function is
+ implemented using a hardware accelerator. This will improve the
+ performance not only of hline() itself, but also of many other
+ functions that use it as a workhorse, for example circlefill(),
+ triangle(), and floodfill().
+
+
+ GFX_HW_HLINE_XOR:
+ Indicates that the XOR version of the hline() function, and any other
+ functions that use it as a workhorse, are implemented using a hardware
+ accelerator.
+
+
+ GFX_HW_HLINE_SOLID_PATTERN:
+ Indicates that the solid and masked pattern modes of the hline()
+ function, and any other functions that use it as a workhorse, are
+ implemented using a hardware accelerator (see note below).
+
+
+ GFX_HW_HLINE_COPY_PATTERN:
+ Indicates that the copy pattern mode of the hline() function, and any
+ other functions that use it as a workhorse, are implemented using a
+ hardware accelerator (see note below).
+
+
+ GFX_HW_FILL:
+ Indicates that the opaque version of the rectfill() function, the
+ clear_bitmap() routine, and clear_to_color(), are implemented using a
+ hardware accelerator.
+
+
+ GFX_HW_FILL_XOR:
+ Indicates that the XOR version of the rectfill() function is
+ implemented using a hardware accelerator.
+
+
+ GFX_HW_FILL_SOLID_PATTERN:
+ Indicates that the solid and masked pattern modes of the rectfill()
+ function are implemented using a hardware accelerator (see note below).
+
+
+ GFX_HW_FILL_COPY_PATTERN:
+ Indicates that the copy pattern mode of the rectfill() function is
+ implemented using a hardware accelerator (see note below).
+
+
+ GFX_HW_LINE:
+ Indicates that the opaque mode line() and vline() functions are
+ implemented using a hardware accelerator.
+
+
+ GFX_HW_LINE_XOR:
+ Indicates that the XOR version of the line() and vline() functions are
+ implemented using a hardware accelerator.
+
+
+ GFX_HW_TRIANGLE:
+ Indicates that the opaque mode triangle() function is implemented
+ using a hardware accelerator.
+
+
+ GFX_HW_TRIANGLE_XOR:
+ Indicates that the XOR version of the triangle() function is
+ implemented using a hardware accelerator.
+
+
+ GFX_HW_GLYPH:
+ Indicates that monochrome character expansion (for text drawing) is
+ implemented using a hardware accelerator.
+
+
+ GFX_HW_VRAM_BLIT:
+ Indicates that blitting from one part of the screen to another is
+ implemented using a hardware accelerator. If this flag is set,
+ blitting within the video memory will almost certainly be the fastest
+ possible way to display an image, so it may be worth storing some of
+ your more frequently used graphics in an offscreen portion of the
+ video memory.
+
+
+ GFX_HW_VRAM_BLIT_MASKED:
+ Indicates that the masked_blit() routine is capable of a hardware
+ accelerated copy from one part of video memory to another, and that
+ draw_sprite() will use a hardware copy when given a sub-bitmap of the
+ screen or a video memory bitmap as the source image. If this flag is
+ set, copying within the video memory will almost certainly be the
+ fastest possible way to display an image, so it may be worth storing
+ some of your more frequently used sprites in an offscreen portion of
+ the video memory.
+
+
+ Warning: if this flag is not set, masked_blit() and draw_sprite() will
+ not work correctly when used with a video memory source image! You
+ must only try to use these functions to copy within the video memory
+ if they are supported in hardware.
+
+
+ GFX_HW_MEM_BLIT:
+ Indicates that blitting from a memory bitmap onto the screen is being
+ accelerated in hardware.
+
+
+ GFX_HW_MEM_BLIT_MASKED:
+ Indicates that the masked_blit() and draw_sprite() functions are being
+ accelerated in hardware when the source image is a memory bitmap and
+ the destination is the physical screen.
+
+
+ GFX_HW_SYS_TO_VRAM_BLIT:
+ Indicates that blitting from a system bitmap onto the screen is being
+ accelerated in hardware. Note that some acceleration may be present
+ even if this flag is not set, because system bitmaps can benefit from
+ normal memory to screen blitting as well. This flag will only be set
+ if system bitmaps have further acceleration above and beyond what is
+ provided by GFX_HW_MEM_BLIT.
+
+
+ GFX_HW_SYS_TO_VRAM_BLIT_MASKED:
+ Indicates that the masked_blit() and draw_sprite() functions are being
+ accelerated in hardware when the source image is a system bitmap and
+ the destination is the physical screen. Note that some acceleration
+ may be present even if this flag is not set, because system bitmaps
+ can benefit from normal memory to screen blitting as well. This flag
+ will only be set if system bitmaps have further acceleration above and
+ beyond what is provided by GFX_HW_MEM_BLIT_MASKED.
+
+
+ GFX_HW_VRAM_STRETCH_BLIT:
+ Indicates that stretched blitting of video bitmaps onto the screen is
+ implemented using hardware acceleration.
+
+
+ GFX_HW_SYS_STRETCH_BLIT:
+ Indicates that stretched blitting of system bitmaps onto the screen is
+ implemented using hardware acceleration.
+
+
+ GFX_HW_VRAM_STRETCH_BLIT_MASKED:
+ Indicates that masked stretched blitting (including stretch_sprite) of
+ video bitmaps onto the screen is implemented using hardware acceleration.
+ NOTE: some display drivers may show artefacts when this function is used.
+ If the image does not look correct try updating your video drivers.
+
+
+ GFX_HW_SYS_STRETCH_BLIT_MASKED:
+ Indicates that masked stretched blitting (including stretch_sprite) of
+ system bitmaps onto the screen is implemented using hardware acceleration.
+ NOTE: some display drivers may show artefacts when this function is used.
+ If the image does not look correct try updating your video drivers.
+
+
+ Note: even if the capabilities information says that patterned drawing is
+ supported by the hardware, it will not be possible for every size of
+ pattern. VBE/AF only supports patterns up to 8x8 in size, so Allegro will
+ fall back on the original non-accelerated drawing routines whenever you
+ use a pattern larger than this.
+
+
+ Note2: these hardware acceleration features will only take effect when
+ you are drawing directly onto the screen bitmap, a video memory bitmap,
+ or a sub-bitmap thereof. Accelerated hardware is most useful in a page
+ flipping or triple buffering setup, and is unlikely to make any
+ difference to the classic "draw onto a memory bitmap, then blit to the
+ screen" system.
+
+
+
+ If the GFX_CAN_TRIPLE_BUFFER bit of the gfx_capabilities field is not
+ set, you can attempt to enable it by calling this function. In particular
+ if you are running in mode-X in a clean DOS environment, this routine
+ will enable the timer retrace simulator, which will activate the triple
+ buffering functions.
+
Return value:
+ Returns zero if triple buffering is enabled, -1 otherwise.
+
+
+
+ Attempts to scroll the hardware screen to display a different part of the
+ virtual screen (initially it will be positioned at 0, 0, which is the top
+ left corner). You can use this to move the screen display around in a
+ large virtual screen space, or to page flip back and forth between two
+ non-overlapping areas of the virtual screen. Note that to draw outside the
+ original position in the screen bitmap you will have to alter the clipping
+ rectangle with set_clip_rect().
+
+
+ Mode-X scrolling is reliable and will work on any card, other drivers may
+ not work or not work reliably. See the platform-specific section of the docs
+ for more information.
+
+
+ Allegro will handle any necessary vertical retrace synchronisation when
+ scrolling the screen, so you don't need to call vsync() before it. This
+ means that scroll_screen() has the same time delay effects as vsync().
+
Return value:
+ Returns zero on success. Returns non-zero if the graphics driver can't
+ handle hardware scrolling or the virtual screen is not large enough.
+
+
+
+ This function is used for triple buffering. It requests a hardware scroll
+ to the specified position, but returns immediately rather than waiting
+ for a retrace. The scroll will then take place during the next vertical
+ retrace, but you can carry on running other code in the meantime and use
+ the poll_scroll() routine to detect when the flip has actually taken
+ place.
+
+
+ Triple buffering is only possible with certain drivers: you can look at the
+ GFX_CAN_TRIPLE_BUFFER bit in the gfx_capabilities flag to see if it will
+ work with the current driver.
+
Return value:
+ This function returns zero on success, non-zero otherwise.
+
+
+
+ Attempts to page flip the hardware screen to display the specified video
+ bitmap object, which must be the same size as the physical screen, and
+ should have been obtained by calling the create_video_bitmap() function.
+
+
+ Allegro will handle any necessary vertical retrace synchronisation when
+ page flipping, so you don't need to call vsync() before it. This means
+ that show_video_bitmap() has the same time delay effects as vsync() by
+ default. This can be adjusted with the "disable_vsync" config key in the
+ [graphics] section of allegro.cfg. Example:
+
+ This function is used for triple buffering. It requests a page flip to
+ display the specified video bitmap object, but returns immediately rather
+ than waiting for a retrace. The flip will then take place during the next
+ vertical retrace, but you can carry on running other code in the meantime
+ and use the poll_scroll() routine to detect when the flip has actually
+ taken place. Triple buffering is only possible on certain hardware: see
+ the comments about request_scroll(). Example:
+
+ Waits for a vertical retrace to begin. The retrace happens when the
+ electron beam in your monitor has reached the bottom of the screen and is
+ moving back to the top ready for another scan. During this short period
+ the graphics card isn't sending any data to the monitor, so you can do
+ things to it that aren't possible at other times, such as altering the
+ palette without causing flickering (snow). Allegro will automatically
+ wait for a retrace before altering the palette or doing any hardware
+ scrolling, though, so you don't normally need to bother with this
+ function.
+
+
+
+
+
screen — Global pointer to the screen hardware video memory.
+
SCREEN_H — Global define to obtain the size of the screen.
+
SCREEN_W — Global define to obtain the size of the screen.
+
set_clip_rect — Sets the clipping rectangle of a bitmap.
+
set_clip_state — Turns on or off the clipping of a bitmap.
+
VIRTUAL_H — Global define to obtain the virtual size of the screen.
+
VIRTUAL_W — Global define to obtain the virtual size of the screen.
+
+
+
+Once you have selected a graphics mode, you can draw things onto the display
+via the `screen' bitmap. All the Allegro graphics routines draw onto BITMAP
+structures, which are areas of memory containing rectangular images, stored
+as packed byte arrays (in 8-bit modes one byte per pixel, in 15- and 16-bit
+modes two bytes per pixel, in 24-bit modes 3 bytes per pixel and in 32-bit
+modes 4 bytes per pixel). You can create and manipulate bitmaps in system
+RAM, or you can write to the special `screen' bitmap which represents the
+video memory in your graphics card.
+
+
+Read chapter "Direct access to video memory" for information on how to get
+direct access to the image memory in a bitmap.
+
+
+Allegro supports several different types of bitmaps:
+
+ The `screen' bitmap, which represents the hardware video memory. Ultimately
+ you have to draw onto this in order for your image to be visible. It is
+ destroyed by any subsequent calls to set_gfx_mode(), so you should never
+ attempt to destroy it yourself.
+
+ Memory bitmaps, which are located in system RAM and can be used to store
+ graphics or as temporary drawing spaces for double buffered systems. These
+ can be obtained by calling create_bitmap(), load_pcx(), or by loading a
+ grabber datafile.
+
+ Sub-bitmaps. These share image memory with a parent bitmap (which can be
+ the screen, a video or system bitmap, a memory bitmap, or another
+ sub-bitmap), so drawing onto them will also change their parent. They can
+ be of any size and located anywhere within the parent bitmap, and can have
+ their own clipping rectangles, so they are a useful way of dividing a
+ bitmap into several smaller units, eg. splitting a large virtual screen
+ into multiple sections (see examples/exscroll.c).
+
+ Warning: Make sure not to destroy a bitmap before all of its sub-bitmaps,
+ otherwise bad things will happen when you try to access one of these
+ sub-bitmaps.
+
+ Video memory bitmaps. These are created by the create_video_bitmap()
+ function, and are usually implemented as sub-bitmaps of the screen object.
+ They must be destroyed by destroy_bitmap() before any subsequent calls to
+ set_gfx_mode().
+
+ System bitmaps. These are created by the create_system_bitmap() function,
+ and are a sort of halfway house between memory and video bitmaps. They
+ live in system memory, so you aren't limited by the amount of video ram in
+ your card, but they are stored in a platform-specific format that may
+ enable better hardware acceleration than is possible with a normal memory
+ bitmap (see the GFX_HW_SYS_TO_VRAM_BLIT and GFX_HW_SYS_TO_VRAM_BLIT_MASKED
+ flags in gfx_capabilities). System bitmaps must be accessed in the same way
+ as video bitmaps, using the bank switch functions and bmp_write*() macros.
+ Not every platform implements this type of bitmap: if they aren't
+ available, create_system_bitmap() will function identically to
+ create_bitmap(). They must be destroyed by destroy_bitmap() before any
+ subsequent calls to set_gfx_mode().
+
+ Global pointer to a bitmap, sized VIRTUAL_W x VIRTUAL_H. This is created
+ by set_gfx_mode(), and represents the hardware video memory. Only a part
+ of this bitmap will actually be visible, sized SCREEN_W x SCREEN_H.
+ Normally this is the top left corner of the larger virtual screen, so you
+ can ignore the extra invisible virtual size of the bitmap if you aren't
+ interested in hardware scrolling or page flipping. To move the visible
+ window to other parts of the screen bitmap, call scroll_screen().
+ Initially the clipping rectangle will be limited to the physical screen
+ size, so if you want to draw onto a larger virtual screen space outside
+ this rectangle, you will need to adjust the clipping.
+
+
+ For example, to draw a pixel onto the screen you would write:
+
+ /* Make a bitmap in RAM. */
+ BITMAP *bmp = create_bitmap(320, 200);
+ /* Clean the memory bitmap. */
+ clear_bitmap(bmp);
+ /* Draw onto the memory bitmap. */
+ putpixel(bmp, x, y, color);
+ /* Copy it to the screen. */
+ blit(bmp, screen, 0, 0, 0, 0, 320, 200);
+
+
+ Warning: be very careful when using this pointer at the same time as any
+ bitmaps created by the create_video_bitmap() function (see the description
+ of this function for more detailed information). And never try to destroy
+ it with destroy_bitmap().
+
+
+
+ Creates a memory bitmap sized width by height. The bitmap will have
+ clipping turned on, and the clipping rectangle set to the full size of the
+ bitmap. The image memory will not be cleared, so it will probably contain
+ garbage: you should clear the bitmap before using it. This routine always
+ uses the global pixel format, as specified by calling set_color_depth().
+ The minimum height of the BITMAP must be 1 and width can't be negative.
+ Example:
+
+ /* Create a 10 pixel tall bitmap, as wide as the screen. */
+ BITMAP *bmp = create_bitmap(SCREEN_W, 10);
+ if (!bmp)
+ abort_on_error("Couldn't create bitmap!");
+ /* Use the bitmap. */
+ ...
+ /* Destroy it when we don't need it any more. */
+ destroy_bitmap(bmp);
+
Return value:
+ Returns a pointer to the created bitmap, or NULL if the bitmap could not
+ be created. Remember to free this bitmap later to avoid memory leaks.
+
+
+
+ Creates a bitmap in a specific color depth (8, 15, 16, 24 or 32 bits per
+ pixel). Example:
+
+ /* Create screen sized bitmap in 32 bits per pixel. /*
+ BITMAP *bmp = create_bitmap_ex(32, SCREEN_W, SCREEN_H);
+ if (!bmp)
+ abort_on_error("Couldn't create bitmap!");
+ /* Use the bitmap. */
+ ...
+ /* Destroy it when we don't need it any more. */
+ destroy_bitmap(bmp);
+
Return value:
+ Returns a pointer to the created bitmap, or NULL if the bitmap could not
+ be created. Remember to free this bitmap later to avoid memory leaks.
+
+
+
+
+ Creates a sub-bitmap, ie. a bitmap sharing drawing memory with a
+ pre-existing bitmap, but possibly with a different size and clipping
+ settings. When creating a sub-bitmap of the mode-X screen, the x position
+ must be a multiple of four. The sub-bitmap width and height can extend
+ beyond the right and bottom edges of the parent (they will be clipped),
+ but the origin point must lie within the parent region.
+
Return value:
+ Returns a pointer to the created sub bitmap, or NULL if the sub bitmap
+ could not be created. Remember to free the sub bitmap before freeing
+ the parent bitmap to avoid memory leaks and potential crashes accessing
+ memory which has been freed.
+
+
+
+ Allocates a video memory bitmap of the specified size. This can be used
+ to allocate offscreen video memory for storing source graphics ready for
+ a hardware accelerated blitting operation, or to create multiple video
+ memory pages which can then be displayed by calling show_video_bitmap().
+ Read the introduction of this chapter for a comparison with other types
+ of bitmaps and other specific details.
+
+
+ Warning: video memory bitmaps are usually allocated from the same space
+ as the screen bitmap, so they may overlap with it; it is therefore not
+ a good idea to use the global screen at the same time as any surfaces
+ returned by this function.
+
Return value:
+ Returns a pointer to the bitmap on success, or NULL if you have run out
+ of video ram. Remember to destroy this bitmap before any subsequent
+ call to set_gfx_mode().
+
+
+
+ Allocates a system memory bitmap of the specified size. Read the
+ introduction of this chapter for a comparison with other types of bitmaps
+ and other specific details.
+
Return value:
+ Returns a pointer to the bitmap on success, NULL otherwise. Remember to
+ destroy this bitmap before any subsequent call to set_gfx_mode().
+
+
+
+ Destroys a memory bitmap, sub-bitmap, video memory bitmap, or system
+ bitmap when you are finished with it. If you pass a NULL pointer this
+ function won't do anything. See above for the restrictions as to when you
+ are allowed to destroy the various types of bitmaps.
+
+
+ The bitmap must not have a mouse cursor shown on it at the time it is
+ destroyed.
+
+
+
+ Under DOS, locks all the memory used by a bitmap. You don't normally need
+ to call this function unless you are doing very weird things in your
+ program.
+
+
+ Returns the mask color for the specified bitmap (the value which is
+ skipped when drawing sprites). For 256-color bitmaps this is zero, and
+ for truecolor bitmaps it is bright pink (maximum red and blue, zero
+ green). A frequent use of this function is to clear a bitmap with the mask
+ color so you can later use this bitmap with masked_blit() or
+ draw_sprite() after drawing other stuff on it. Example:
+
+ /* Replace mask color with another color. */
+ for (y = 0; y < bmp->h; y++)
+ for (x = 0; x < bmp->w; x++)
+ if (getpixel(bmp, x, y) == bitmap_mask_color(bmp))
+ putpixel(bmp, x, y, another_color);
+ Returns TRUE if the two bitmaps describe the same drawing surface, ie.
+ the pointers are equal, one is a sub-bitmap of the other, or they are
+ both sub-bitmaps of a common parent.
+
+
+
+ Returns TRUE if bmp is a linear bitmap, i.e. a bitmap that can be accessed
+ linearly within each scanline (for example a memory bitmap, the DOS VGA
+ or SVGA screen, Windows bitmaps, etc). Linear bitmaps can be used with the
+ _putpixel(), _getpixel(), bmp_write_line(), and bmp_read_line() functions.
+
+
+ Historically there were only linear and planar bitmaps for Allegro, so
+ is_linear_bitmap() is actually an alias for !is_planar_bitmap().
+
+
+
+ Returns TRUE if bmp is a memory bitmap, ie. it was created by calling
+ create_bitmap() or loaded from a grabber datafile or image file. Memory
+ bitmaps can be accessed directly via the line pointers in the bitmap
+ structure, eg. bmp->line[y][x] = color.
+
+
+
+ Acquires the specified video bitmap prior to drawing onto it. You never need
+ to call the function explicitly as it is low level, and will only give you a
+ speed up if you know what you are doing. Using it wrongly may cause slowdown,
+ or even lock up your program.
+
+
+ Note: You do never need to use acquire_bitmap on a memory bitmap, i.e. a
+ normal bitmap created with create_bitmap. It will simply do nothing in that
+ case.
+
+
+ It still can be useful, because e.g. under the current DirectDraw driver of
+ Allegro, most drawing functions need to lock a video bitmap before drawing to
+ it. But doing this is very slow, so you will get much better performance if
+ you acquire the screen just once at the start of your main redraw function,
+ then call multiple drawing operations which need the bitmap locked, and only
+ release it when done.
+
+
+ Multiple acquire calls may be nested, but you must make sure to match up the
+ acquire_bitmap and release_bitmap calls. Be warned that DirectX and X11
+ programs activate a mutex lock whenever a surface is locked, which prevents
+ them from getting any input messages, so you must be sure to release all your
+ bitmaps before using any timer, keyboard, or other non-graphics routines!
+
+
+ Note that if you are using hardware accelerated VRAM->VRAM functions, you
+ should not call acquire_bitmap(). Such functions need an unlocked target
+ bitmap under DirectX, so there is now just the opposite case from before - if
+ the bitmap is already locked with acquire_bitmap, the drawing
+ operation has to unlock it.
+
+
+ Note: For backwards compatibility, the unlocking behavior of such functions
+ is permanent. That is, if you call acquire_bitmap first, then call e.g. an
+ accelerated blit, the DirectX bitmap will be unlocked internally (it won't
+ affect the nesting counter of acquire/release calls).
+
+
+ There is no clear cross-platform way in this Allegro version to know which
+ drawing operations need a locked/unlocked state. For example a normal
+ rectfill most probably is accelerated under DirectX, and therefore needs the
+ screen unlocked, but an XOR rectfill, or one with blending activated, most
+ probably is not, and therefore locks the screen. And while the DirectX driver
+ will do automatic unlocking, there is no such thing under X11, where the
+ function is used to synchronize X11 calls from different threads. Your best
+ bet is to never use acquire_bitmap - changes are you are doing something in
+ the wrong way if you think you need it.
+
+
+ Warning: This function can be very dangerous to use, since the whole program
+ may get locked while the bitmap is locked. So the lock should only be held
+ for a short time, and you should not call anything but drawing operations
+ onto the locked video bitmap while a lock is in place. Especially don't call
+ things like show_mouse (or scare_mouse which calls that) or readkey, since
+ it will most likely deadlock your entire program.
+
+
+
+ Releases a bitmap that was previously locked by calling acquire_bitmap().
+ If the bitmap was locked multiple times, you must release it the same
+ number of times before it will truly be unlocked.
+
+
+
+ Each bitmap has an associated clipping rectangle, which is the area of
+ the image that it is ok to draw onto. Nothing will be drawn to positions
+ outside this space. This function sets the clipping rectangle for the
+ specified bitmap. Pass the coordinates of the top-left and bottom-right
+ corners of the clipping rectangle in this order; these are both inclusive,
+ i.e. set_clip_rect(bitmap, 16, 16, 32, 32) will allow drawing to (16, 16)
+ and (32, 32), but not to (15, 15) and (33, 33).
+
+
+ Drawing operations will be performed (at least partially) on the bitmap as
+ long as the first coordinates of its clipping rectangle are not greater
+ than the second coordinates and its intersection with the actual image
+ is non-empty. If either condition is not fulfilled, drawing will be turned
+ off for the bitmap, e.g.
+
+ Note that passing "out-of-bitmap" coordinates is allowed, but they are
+ likely to be altered (and so the coordinates returned by get_clip_rect()
+ will be different). However, such modifications are guaranteed to preserve
+ the external effect of the clipping rectangle, that is not to modify the
+ actual area of the image that it is ok to draw onto.
+
+
+
+ Sets the clipping rectangle of the specified bitmap as the intersection of
+ its current clipping rectangle and the rectangle described by the four
+ coordinates.
+
+
+
+ Turns on (if state is non-zero) or off (if state is zero) clipping for the
+ specified bitmap. Turning clipping off may slightly speed up some drawing
+ operations (usually a negligible difference, although every little helps)
+ but will result in your program dying a horrible death if you try to draw
+ beyond the edges of the bitmap.
+
+
+
+ Returns non-zero if point (x, y) lies inside the bitmap. If `clip' is
+ non-zero, the function compares the coordinates with the clipping
+ rectangle, that is it returns non-zero if the point lies inside the
+ clipping rectangle or if clipping is disabled for the bitmap. If `clip'
+ is zero, the function compares the coordinates with the actual dimensions
+ of the bitmap.
+
+
+
+
+
set_color_conversion — Tells Allegro how to convert images during loading time.
+
+
+
+Warning: when using truecolor images, you should always set the graphics
+mode before loading any bitmap data! Otherwise the pixel format (RGB or BGR)
+will not be known, so the file may be converted wrongly.
+
+
+ Loads a bitmap from a file. The palette data will be stored in the second
+ parameter, which should be an array of 256 RGB structures. At present this
+ function supports BMP, LBM, PCX, and TGA files, determining the type from
+ the file extension.
+
+
+ If the file contains a truecolor image, you must set the video mode or
+ call set_color_conversion() before loading it. In this case, if the
+ destination color depth is 8-bit, the palette will be generated by calling
+ generate_optimized_palette() on the bitmap; otherwise, the returned
+ palette will be generated by calling generate_332_palette().
+
+
+ The pal argument may be NULL. In this case, the palette data are simply
+ not returned. Additionally, if the file is a truecolor image and the
+ destination color depth is 8-bit, the color conversion process will use
+ the current palette instead of generating an optimized one.
+
+
Return value:
+ Returns a pointer to the bitmap or NULL on error. Remember that you are
+ responsible for destroying the bitmap when you are finished with it to
+ avoid memory leaks.
+
+
+
+ Loads an 8-bit, 16-bit, 24-bit or 32-bit Windows or OS/2 BMP file.
+
Return value:
+ Returns a pointer to the bitmap or NULL on error. Remember that you are
+ responsible for destroying the bitmap when you are finished with it to
+ avoid memory leaks.
+
+
+
Return value:
+ Returns a pointer to the bitmap or NULL on error. Remember that you are
+ responsible for destroying the bitmap when you are finished with it to
+ avoid memory leaks.
+
+
+
Return value:
+ Returns a pointer to the bitmap or NULL on error. Remember that you are
+ responsible for destroying the bitmap when you are finished with it to
+ avoid memory leaks.
+
+
+
+ Loads a 256-color or 24-bit truecolor PCX file.
+
Return value:
+ Returns a pointer to the bitmap or NULL on error. Remember that you are
+ responsible for destroying the bitmap when you are finished with it to
+ avoid memory leaks.
+
+
+
Return value:
+ Returns a pointer to the bitmap or NULL on error. Remember that you are
+ responsible for destroying the bitmap when you are finished with it to
+ avoid memory leaks.
+
+
+
+ Loads a 256-color, 15-bit hicolor, 24-bit truecolor, or 32-bit
+ truecolor+alpha TGA file.
+
Return value:
+ Returns a pointer to the bitmap or NULL on error. Remember that you are
+ responsible for destroying the bitmap when you are finished with it to
+ avoid memory leaks.
+
+
+
Return value:
+ Returns a pointer to the bitmap or NULL on error. Remember that you are
+ responsible for destroying the bitmap when you are finished with it to
+ avoid memory leaks.
+
+
+
+ Writes a bitmap into a file, using the specified palette, which should be
+ an array of 256 RGB structures. The output format is determined from the
+ filename extension: at present this function supports BMP, PCX and TGA
+ formats.
+
+
+ Two things to watch out for: on some video cards it may be faster to copy
+ the screen to a memory bitmap and save the latter, and if you use this to
+ dump the screen into a file you may end up with an image much larger than
+ you were expecting, because Allegro often creates virtual screens larger
+ than the visible screen. You can get around this by using a sub-bitmap to
+ specify which part of the screen to save, eg:
+
+ Informs the load_bitmap() and save_bitmap() functions of a new file type,
+ providing routines to read and write images in this format (either
+ function may be NULL). The functions you supply must follow the same
+ prototype as load_bitmap() and save_bitmap(). Example:
+
+ Specifies how to convert images between the various color depths when
+ reading graphics from external bitmap files or datafiles. The mode is a
+ bitmask specifying which types of conversion are allowed. If the
+ appropriate bit is set, data will be converted into the current pixel
+ format (selected by calling the set_color_depth() function), otherwise it
+ will be left in the same format as the disk file, leaving you to convert
+ it manually before the graphic can be displayed. The default mode is
+ total conversion, so that all images will be loaded in the appropriate
+ format for the current video mode. Valid bit flags are:
+
+ COLORCONV_NONE // disable all format
+ // conversions
+ COLORCONV_8_TO_15 // expand 8-bit to 15-bit
+ COLORCONV_8_TO_16 // expand 8-bit to 16-bit
+ COLORCONV_8_TO_24 // expand 8-bit to 24-bit
+ COLORCONV_8_TO_32 // expand 8-bit to 32-bit
+ COLORCONV_15_TO_8 // reduce 15-bit to 8-bit
+ COLORCONV_15_TO_16 // expand 15-bit to 16-bit
+ COLORCONV_15_TO_24 // expand 15-bit to 24-bit
+ COLORCONV_15_TO_32 // expand 15-bit to 32-bit
+ COLORCONV_16_TO_8 // reduce 16-bit to 8-bit
+ COLORCONV_16_TO_15 // reduce 16-bit to 15-bit
+ COLORCONV_16_TO_24 // expand 16-bit to 24-bit
+ COLORCONV_16_TO_32 // expand 16-bit to 32-bit
+ COLORCONV_24_TO_8 // reduce 24-bit to 8-bit
+ COLORCONV_24_TO_15 // reduce 24-bit to 15-bit
+ COLORCONV_24_TO_16 // reduce 24-bit to 16-bit
+ COLORCONV_24_TO_32 // expand 24-bit to 32-bit
+ COLORCONV_32_TO_8 // reduce 32-bit RGB to 8-bit
+ COLORCONV_32_TO_15 // reduce 32-bit RGB to 15-bit
+ COLORCONV_32_TO_16 // reduce 32-bit RGB to 16-bit
+ COLORCONV_32_TO_24 // reduce 32-bit RGB to 24-bit
+ COLORCONV_32A_TO_8 // reduce 32-bit RGBA to 8-bit
+ COLORCONV_32A_TO_15 // reduce 32-bit RGBA to 15-bit
+ COLORCONV_32A_TO_16 // reduce 32-bit RGBA to 16-bit
+ COLORCONV_32A_TO_24 // reduce 32-bit RGBA to 24-bit
+ COLORCONV_DITHER_PAL // dither when reducing to 8-bit
+ COLORCONV_DITHER_HI // dither when reducing to
+ // hicolor
+ COLORCONV_KEEP_TRANS // keep original transparency
+
+ For convenience, the following macros can be used to select common
+ combinations of these flags:
+
+ COLORCONV_EXPAND_256 // expand 256-color to hi/truecolor
+ COLORCONV_REDUCE_TO_256 // reduce hi/truecolor to 256-color
+ COLORCONV_EXPAND_15_TO_16 // expand 15-bit hicolor to 16-bit
+ COLORCONV_REDUCE_16_TO_15 // reduce 16-bit hicolor to 15-bit
+ COLORCONV_EXPAND_HI_TO_TRUE // expand 15/16-bit to 24/32-bit
+ COLORCONV_REDUCE_TRUE_TO_HI // reduce 24/32-bit to 15/16-bit
+ COLORCONV_24_EQUALS_32 // convert between 24- and 32-bit
+ COLORCONV_TOTAL // everything to current format
+ COLORCONV_PARTIAL // convert 15 <-> 16-bit and
+ // 24 <-> 32-bit
+ COLORCONV_MOST // all but hi/truecolor <-> 256
+ COLORCONV_DITHER // dither during all color reductions
+ COLORCONV_KEEP_ALPHA // convert everything to current format
+ // unless it would lose alpha information
+
+ If you enable the COLORCONV_DITHER flag, dithering will be performed
+ whenever truecolor graphics are converted into a hicolor or paletted
+ format, including by the blit() function, and any automatic conversions
+ that take place while reading graphics from disk. This can produce much
+ better looking results, but is obviously slower than a direct conversion.
+
+
+ If you intend using converted bitmaps with functions like masked_blit()
+ or draw_sprite(), you should specify the COLORCONV_KEEP_TRANS flag. It
+ will ensure that the masked areas in the bitmap before and after the
+ conversion stay exactly the same, by mapping transparent colors to each
+ other and adjusting colors which would be converted to the transparent
+ color otherwise. It affects every blit() operation between distinct pixel
+ formats and every automatic conversion.
+
+
+
unselect_palette — Restores the palette before last call to select_palette().
+
+
+
+All the Allegro drawing functions use integer parameters to represent
+colors. In truecolor resolutions these numbers encode the color directly as
+a collection of red, green, and blue bits, but in a regular 256-color mode
+the values are treated as indexes into the current palette, which is a table
+listing the red, green and blue intensities for each of the 256 possible
+colors.
+
+
+Palette entries are stored in an RGB structure, which contains red, green
+and blue intensities in the VGA hardware format, ranging from 0-63, and is
+defined as:
+
+The type PALETTE is defined to be an array of PAL_SIZE RGB structures, where
+PAL_SIZE is a preprocessor constant equal to 256.
+
+
+You may notice that a lot of the code in Allegro spells 'palette' as
+'pallete'. This is because the headers from my old Mark Williams compiler on
+the Atari spelt it with two l's, so that is what I'm used to. Allegro will
+happily accept either spelling, due to some #defines in allegro/alcompat.h
+(which can be turned off by defining the ALLEGRO_NO_COMPATIBILITY symbol
+before including Allegro headers).
+
+
+ Sets the specified palette entry to the specified RGB triplet. Unlike the
+ other palette functions this doesn't do any retrace synchronisation, so
+ you should call vsync() before it to prevent snow problems. Example:
+
+ This is an inline version of set_color(), intended for use in the
+ vertical retrace simulator callback function (retrace_proc, which is now
+ deprecated).
+
+
+ If you really must use _set_color from retrace_proc, note that it should
+ only be used under DOS, in VGA mode 13h and mode-X. Some SVGA chipsets
+ aren't VGA compatible (set_color() and set_palette() will use VESA calls on
+ these cards, but _set_color() doesn't know about that).
+
+
+
+ Sets the entire palette of 256 colors. You should provide an array of 256
+ RGB structures. Unlike set_color(), there is no need to call vsync()
+ before this function. Example:
+
+ Sets the palette entries between from and to (inclusive: pass 0 and 255
+ to set the entire palette). If vsync is set it waits for the vertical
+ retrace, otherwise it sets the colors immediately. Example:
+
+ PALETTE palette;
+ ...
+ /* Modify the first 16 entries. */
+ change_first_16_colors(palette);
+ /* Now update them waiting for vsync. */
+ set_palette_range(palette, 0, 15, 1);
+ Calculates a temporary palette part way between source and dest,
+ returning it in the output parameter. The position between the two
+ extremes is specified by the pos value: 0 returns an exact copy of
+ source, 64 returns dest, 32 returns a palette half way between the two,
+ etc. This routine only affects colors between from and to (inclusive:
+ pass 0 and 255 to interpolate the entire palette).
+
+
+
+ Gradually fades a part of the palette from the source palette to the dest
+ palette. The speed is from 1 (the slowest) up to 64 (instantaneous). This
+ routine only affects colors between from and to (inclusive: pass 0 and
+ 255 to fade the entire palette).
+
+
+ Note that this function will block your game while the fade is in effect,
+ and it won't work right visually if you are not in an 8 bit color depth
+ resolution.
+
+
+
+ Gradually fades a part of the palette from a black screen to the
+ specified palette. The speed is from 1 (the slowest) up to 64
+ (instantaneous). This routine only affects colors between from and to
+ (inclusive: pass 0 and 255 to fade the entire palette).
+
+
+ Note that this function will block your game while the fade is in effect,
+ and it won't work right visually if you are not in an 8 bit color depth
+ resolution.
+
+
+
+ Gradually fades a part of the palette from the current palette to a black
+ screen. The speed is from 1 (the slowest) up to 64 (instantaneous). This
+ routine only affects colors between from and to (inclusive: pass 0 and
+ 255 to fade the entire palette).
+
+
+ Note that this function will block your game while the fade is in effect,
+ and it won't work right visually if you are not in an 8 bit color depth
+ resolution.
+
+
+
+ Fades gradually from the source palette to the dest palette. The speed is
+ from 1 (the slowest) up to 64 (instantaneous).
+
+
+ Note that this function will block your game while the fade is in effect,
+ and it won't work right visually if you are not in an 8 bit color depth
+ resolution.
+
+
+
+ Fades gradually from a black screen to the specified palette. The speed
+ is from 1 (the slowest) up to 64 (instantaneous).
+
+
+ Note that this function will block your game while the fade is in effect,
+ and it won't work right visually if you are not in an 8 bit color depth
+ resolution.
+
+
+
+ Fades gradually from the current palette to a black screen. The speed is
+ from 1 (the slowest) up to 64 (instantaneous).
+
+
+ Note that this function will block your game while the fade is in effect,
+ and it won't work right visually if you are not in an 8 bit color depth
+ resolution.
+
+
+
+ Ugly hack for use in various dodgy situations where you need to convert
+ between paletted and truecolor image formats. Sets the internal palette
+ table in the same way as the set_palette() function, so the conversion
+ will use the specified palette, but without affecting the display
+ hardware in any way. The previous palette settings are stored in an
+ internal buffer, and can be restored by calling unselect_palette(). If
+ you call select_palette() again, however, the internal buffer will be
+ overwritten.
+
+
+
+ Constructs a fake truecolor palette, using three bits for red and green
+ and two for the blue. The load_bitmap() function fills the palette
+ parameter with this if the file does not contain a palette itself (ie. you
+ are reading a truecolor bitmap).
+
+
+
+ Generates a 256-color palette suitable for making a reduced color version
+ of the specified truecolor image. The rsvd parameter points to a table
+ indicating which colors it is allowed to modify: zero for free colors
+ which may be set to whatever the optimiser likes, negative values for
+ reserved colors which cannot be used, and positive values for fixed
+ palette entries that must not be changed, but can be used in the
+ optimisation.
+
Return value:
+ Returns the number of different colors recognised in the provided bitmap,
+ zero if the bitmap is not a truecolor image or there wasn't enough memory
+ to perform the operation, and negative if there was any internal error in
+ the color reduction code.
+
+
+
+ The default IBM BIOS palette. This will be automatically selected
+ whenever you set a new graphics mode. The palette contains 16 basic
+ colors plus many gradients between them. If you want to see the values,
+ you can write a small Allegro program which saves a screenshot with this
+ palette, or open the grabber tool provided with Allegro and create a new
+ palette object, which will use this palette by default.
+
+
+
+ The palette used by the Atari ST low resolution desktop. I'm not quite
+ sure why this is still here, except that the grabber and test programs
+ use it. It is probably the only Atari legacy code left in Allegro, and it
+ would be a shame to remove it :-)
+
+
+ The contents of this palette are 16 colors repeated 16 times. Color entry
+ zero is equal to color entry 16, which is equal to color entry 24, etc.
+
makecol — Converts an RGB value into the current pixel format.
+
makecol15 — Converts an RGB value into a display dependent pixel format.
+
makecol15_dither — Calculates a dithered 15 or 16-bit RGB value.
+
makecol16 — Converts an RGB value into a display dependent pixel format.
+
makecol16_dither — Calculates a dithered 15 or 16-bit RGB value.
+
makecol24 — Converts an RGB value into a display dependent pixel format.
+
makecol32 — Converts an RGB value into a display dependent pixel format.
+
makecol8 — Converts an RGB value into a display dependent pixel format.
+
makecol_depth — Converts an RGB value into the specified pixel format.
+
MASK_COLOR_15 — Constant representing the mask value in sprites.
+
MASK_COLOR_16 — Constant representing the mask value in sprites.
+
MASK_COLOR_24 — Constant representing the mask value in sprites.
+
MASK_COLOR_32 — Constant representing the mask value in sprites.
+
MASK_COLOR_8 — Constant representing the mask value in sprites.
+
palette_color — Maps palette indexes into the current pixel format colors.
+
+
+
+In a truecolor video mode the red, green, and blue components for each pixel
+are packed directly into the color value, rather than using a palette lookup
+table. In a 15-bit mode there are 5 bits for each color, in 16-bit modes
+there are 5 bits each of red and blue and six bits of green, and both 24 and
+32-bit modes use 8 bits for each color (the 32-bit pixels simply have an
+extra padding byte to align the data nicely). The layout of these components
+can vary depending on your hardware, but will generally either be RGB or
+BGR. Since the layout is not known until you select the video mode you will
+be using, you must call set_gfx_mode() before using any of the following
+routines!
+
+
+ These functions convert colors from a hardware independent form (red,
+ green, and blue values ranging 0-255) into various display dependent
+ pixel formats. Converting to 15, 16, 24, or 32-bit formats only takes a
+ few shifts, so it is fairly efficient. Converting to an 8-bit color
+ involves searching the palette to find the closest match, which is quite
+ slow unless you have set up an RGB mapping table (see below). Example:
+
+ /* 16 bit color version of green. */
+ int green_color = makecol16(0, 255, 0);
+
Return value:
+ Returns the requested RGB triplet in the specified color depth.
+
+
+
+ Converts an RGBA color into a 32-bit display pixel format, which includes
+ an alpha (transparency) value. There are no versions of this routine for
+ other color depths, because only the 32-bit format has enough room to
+ store a proper alpha channel. You should only use RGBA format colors as
+ the input to draw_trans_sprite() or draw_trans_rle_sprite() after calling
+ set_alpha_blender(), rather than drawing them directly to the screen.
+
+
+
+ Converts colors from a hardware independent format (red, green, and blue
+ values ranging 0-255) to the pixel format required by the current video
+ mode, calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as
+ appropriate. Example:
+
+ /* Regardless of color depth, this will look green. */
+ int green_color = makecol(0, 255, 0);
+
Return value:
+ Returns the requested RGB triplet in the current color depth.
+
+
+
int makecol_depth(int color_depth, int r, int g, int b);
+ Converts colors from a hardware independent format (red, green, and blue
+ values ranging 0-255) to the pixel format required by the specified color
+ depth. Example:
+
+ /* Compose the green color for 15 bit color depth. */
+ int green_15bit = makecol_depth(15, 0, 255, 0);
+
Return value:
+ Returns the requested RGB triplet in the specified color depth.
+
+
+
int makeacol_depth(int color_depth, int r, int g, int b, int a);
+ Convert RGBA colors into display dependent pixel formats. In anything
+ less than a 32-bit mode, these are the same as calling makecol() or
+ makecol_depth(), but by using these routines it is possible to create
+ 32-bit color values that contain a true 8 bit alpha channel along with
+ the red, green, and blue components. You should only use RGBA format
+ colors as the input to draw_trans_sprite() or draw_trans_rle_sprite()
+ after calling set_alpha_blender(), rather than drawing them directly to
+ the screen.
+
+ Given both a color value and a pixel coordinate, calculate a dithered 15
+ or 16-bit RGB value. This can produce better results when reducing images
+ from truecolor to hicolor. In addition to calling these functions
+ directly, hicolor dithering can be automatically enabled when loading
+ graphics by calling the set_color_conversion() function, for example
+ set_color_conversion(COLORCONV_REDUCE_TRUE_TO_HI | COLORCONV_DITHER).
+
+
+ Example:
+
+ int pixel1, pixel2;
+
+ /* The following two color values MAY be different. */
+ pixel1 = makecol16_dither(255, 192, 64, 0, 0);
+ pixel2 = makecol16_dither(255, 192, 64, 1, 0);
+
Return value:
+ Returns the RGB value dithered for the specified coordinate.
+
+
+
+ Given a color in the format being used by the current video mode, these
+ functions extract one of the red, green, blue, or alpha components
+ (ranging 0-255), calling the preceding 8, 15, 16, 24, or 32-bit get
+ functions as appropriate. The alpha part is only meaningful for 32-bit
+ pixels. Example:
+
+ int r, g, b, color_value;
+
+ color_value = getpixel(screen, 100, 100);
+ r = getr(color_value);
+ g = getg(color_value);
+ b = getb(color_value);
+ Given a color in the format being used by the specified color depth,
+ these functions extract one of the red, green, blue, or alpha components
+ (ranging 0-255). The alpha part is only meaningful for 32-bit pixels.
+ Example:
+
+ Table mapping palette index colors (0-255) into whatever pixel format is
+ being used by the current display mode. In a 256-color mode this just
+ maps onto the array index. In truecolor modes it looks up the specified
+ entry in the current palette, and converts that RGB value into the
+ appropriate packed pixel format. Example:
+
+ Constants representing the colors used to mask transparent sprite pixels
+ for each color depth. In 256-color resolutions this is zero, and in
+ truecolor modes it is bright pink (maximum red and blue, zero green).
+
+
+
+
+
+Except for _putpixel(), all these routines are affected by the current
+drawing mode and the clipping rectangle of the destination bitmap. Unless
+specified otherwise, all coordinates for drawing operations are inclusive,
+and they, as well as lengths, are specified in pixel units.
+
+
+ Like the regular putpixel(), but much faster because they are implemented
+ as an inline assembler functions for specific color depths. These won't
+ work in mode-X graphics modes, don't perform any clipping (they will
+ crash if you try to draw outside the bitmap!), and ignore the drawing
+ mode.
+
+
+
+ Reads a pixel from point (x, y) in the bitmap.
+
Return value:
+ Returns -1 if the point lies outside the bitmap (ignoring the clipping
+ rectangle), otherwise the value of the pixel in the color format of the
+ bitmap.
+
+
+ Warning: -1 is also a valid value for pixels contained in 32-bit bitmaps
+ with alpha channel (when R,G,B,A are all equal to 255) so you can't use
+ the test against -1 as a predicate for such bitmaps. In this cases, the
+ only reliable predicate is is_inside_bitmap().
+
+
+ To extract the individual color components, use the getr() / getg() /
+ getb() / geta() family of functions.
+
+
+
+ Faster inline versions of getpixel() for specific color depths. These
+ won't work in mode-X, and don't do any clipping, so you must make sure
+ the point lies inside the bitmap.
+
Return value:
+ Returns the value of the pixel in the color format you specified.
+
+
+
void vline(BITMAP *bmp, int x, int y1, int y2, int color);
+ Draws a vertical line onto the bitmap, from point (x, y1) to (x, y2).
+
+
+ Note: vline() is implemented as an alias to another function.
+ See ALLEGRO_NO_VHLINE_ALIAS in the `Differences between platforms'
+ section for details.
+
+
+
void hline(BITMAP *bmp, int x1, int y, int x2, int color);
+ Draws a horizontal line onto the bitmap, from point (x1, y) to (x2, y).
+
+
+ Note: hline() is implemented as an alias to another function.
+ See ALLEGRO_NO_VHLINE_ALIAS in the `Differences between platforms'
+ section for details.
+
+
+
void do_line(BITMAP *bmp, int x1, y1, x2, y2, int d,
+ void (*proc)(BITMAP *bmp, int x, int y, int d));
+ Calculates all the points along a line from point (x1, y1) to (x2, y2),
+ calling the supplied function for each one. This will be passed a copy of
+ the bmp parameter, the x and y position, and a copy of the d parameter,
+ so it is suitable for use with putpixel(). Example:
+
+ void draw_dust_particle(BITMAP *bmp, int x, int y, int d)
+ {
+ ...
+ }
+
+ do_line(screen, 0, 0, SCREEN_W-1, SCREEN_H-2,
+ dust_strength, draw_dust_particle);
void polygon(BITMAP *bmp, int vertices, const int *points, int color);
+ Draws a filled polygon with an arbitrary number of corners. Pass the
+ number of vertices and an array containing a series of x, y points (a
+ total of vertices*2 values). Example:
+
void do_circle(BITMAP *bmp, int x, int y, int radius, int d,
+ void (*proc)(BITMAP *bmp, int x, int y, int d));
+ Calculates all the points in a circle around point (x, y) with radius r,
+ calling the supplied function for each one. This will be passed a copy of
+ the bmp parameter, the x and y position, and a copy of the d parameter,
+ so it is suitable for use with putpixel(). Example:
+
void do_ellipse(BITMAP *bmp, int x, int y, int rx, ry, int d,
+ void (*proc)(BITMAP *bmp, int x, int y, int d));
+ Calculates all the points in an ellipse around point (x, y) with radius
+ rx and ry, calling the supplied function for each one. This will be
+ passed a copy of the bmp parameter, the x and y position, and a copy of
+ the d parameter, so it is suitable for use with putpixel(). Example:
+
void do_arc(BITMAP *bmp, int x, int y, fixed a1, fixed a2, int r, int d,
+ void (*proc)(BITMAP *bmp, int x, int y, int d));
+ Calculates all the points in a circular arc around point (x, y) with
+ radius r, calling the supplied function for each one. This will be passed
+ a copy of the bmp parameter, the x and y position, and a copy of the d
+ parameter, so it is suitable for use with putpixel(). The arc will be
+ plotted in an anticlockwise direction starting from the angle a1 and
+ ending when it reaches a2. These values are specified in 16.16 fixed
+ point format, with 256 equal to a full circle, 64 a right angle, etc.
+ Zero is to the right of the centre point, and larger values rotate
+ anticlockwise from there. Example:
+
void arc(BITMAP *bmp, int x, y, fixed ang1, ang2, int r, int color);
+ Draws a circular arc with centre x, y and radius r, in an anticlockwise
+ direction starting from the angle a1 and ending when it reaches a2. These
+ values are specified in 16.16 fixed point format, with 256 equal to a
+ full circle, 64 a right angle, etc. Zero is to the right of the centre
+ point, and larger values rotate anticlockwise from there. Example:
+
void calc_spline(const int points[8], int npts, int *x, int *y);
+ Calculates a series of npts values along a bezier spline, storing them in
+ the output x and y arrays. The bezier curve is specified by the four x/y
+ control points in the points array: points[0] and points[1] contain the
+ coordinates of the first control point, points[2] and points[3] are the
+ second point, etc. Control points 0 and 3 are the ends of the spline, and
+ points 1 and 2 are guides. The curve probably won't pass through points 1
+ and 2, but they affect the shape of the curve between points 0 and 3 (the
+ lines p0-p1 and p2-p3 are tangents to the spline). The easiest way to
+ think of it is that the curve starts at p0, heading in the direction of
+ p1, but curves round so that it arrives at p3 from the direction of p2.
+ In addition to their role as graphics primitives, spline curves can be
+ useful for constructing smooth paths around a series of control points,
+ as in exspline.c.
+
+
+
void spline(BITMAP *bmp, const int points[8], int color);
+ Draws a bezier spline using the four control points specified in the
+ points array. Read the description of calc_spline() for information on
+ how to build the points array.
+
+
+
stretch_blit — Scales a rectangular area from one bitmap to another.
+
stretch_sprite — Stretches a sprite to the destination bitmap.
+
+
+
+As far as Allegro is concerned, a bitmap and a sprite are the same thing,
+but to many people the two words imply slightly different things. The
+function draw_sprite() is called so rather than draw_bitmap() partly because
+it indicates that it uses a masked drawing mode (if it existed, you could
+expect draw_bitmap() to be a simple block copy), and partly for historical
+reasons. In Allegro 1.0 there were actually different structures for sprites
+and bitmaps, each with their own set of abilities. Allegro 2.0 merged these
+into a single more flexible structure, but retained some names like
+draw_sprite().
+
+
+In wider (non-Allegro) terms, the two words can mean quite different things.
+Generally you can say that sprites are a subset of bitmaps, but even that
+isn't true in 100% of cases.
+
+
+BITMAP: a widely accepted term that will be understood by anyone even
+remotely connected with computer graphics. It simply means an image built up
+from a grid of pixels, ie. just about any picture that you are likely to come
+across on a computer (vector graphics formats are the exception, but those
+must be rendered into a bitmap format before they can be displayed by most
+hardware). A more accurate term but slightly rarer term with the same meaning
+is "pixmap" (pixel-map).
+
+
+SPRITE: a particular usage of bitmapped images, restricted to video games
+(other types of programmer probably won't be familiar with this term).
+Originally on machines like the C64, sprites were a hardware feature that
+allowed a number of small bitmap images to be loaded into special registers,
+and they could then be superimposed over the main graphics display and moved
+around just by modifying the position register. They were used for the moving
+objects (player and enemy characters), and enabled the C64 to do much more
+impressive things than would have been possible if all the drawing had to be
+done directly by the puny CPU.
+
+
+Later on, a lot of old C64 programmers upgraded to machines like the Atari
+ST, which didn't have any special sprite hardware, but they carried on
+referring to their main moving objects as sprites (the routine to draw such a
+thing would obviously be called draw_sprite()). A sprite is really just a
+bitmap graphic which is drawn onto the screen, but when you call it a sprite
+rather than a bitmap, this suggests it is a gameplay element that can move
+freely around the world rather than being a static part of the environment,
+and that it will be drawn in a masked overlay mode rather than as a solid
+rectangle (there is also a strong implication that a sprite will be animated
+by cycling through a number of frames, but that isn't always the case).
+
+
+In recent years some people have started using "sprite" to refer to any
+character graphics, even if they are not in fact drawn as 2d bitmaps, eg.
+"this game uses 3d polygonal player sprites". This is a confusing misuse of
+the word (Doom uses sprites, Quake does not), but it does happen.
+
+
+The origin of the term "blit" is also rather interesting. This was originally
+BitBlt, an abbreviation of BITmap BLock Transfer, which was a function
+designed (possibly) by the people at Xerox who did so much of the pioneering
+work on graphics display systems, and subsequently copied by virtually
+everybody doing computer graphics (the Microsoft Windows GDI still provides a
+BitBlt function with identical functionality to the original). This routine
+was a workhorse for all sorts of drawing operations, basically copying bitmap
+graphics from one place to another, but including a number of different ROP
+modes (Raster OPerations) for doing things like XOR, inverting pixels, etc.
+A whole family of related words grew up around the BitBlt function, but "blt"
+is impossible to speak (try saying "bltter" or "bltting" :-) so people added
+the vowel to make it easier to pronounce.
+
+
+Thusly, the act of calling the BitBlt function came to be known as "doing a
+blit". The obvious next step was to rename the function itself to blit(),
+which generally took place at the same time as people decided to simplify the
+original, removing the different ROP modes on the grounds that they aren't
+needed for games coding and don't work well with anything higher than
+monochrome images in any case. This leaves us with a function called blit(),
+which is an abbreviation for "block transfer". A strong case could be made
+for calling this blot() instead, but somehow that just doesn't sound the
+same!
+
+
+Anyway, all the routines in this chapter are affected by the
+clipping rectangle of the destination bitmap.
+
+
+
void blit(BITMAP *source, BITMAP *dest, int source_x, int source_y,
+ int dest_x, int dest_y, int width, int height);
+ Copies a rectangular area of the source bitmap to the destination bitmap.
+ The source_x and source_y parameters are the top left corner of the area
+ to copy from the source bitmap, and dest_x and dest_y are the
+ corresponding position in the destination bitmap. This routine respects
+ the destination clipping rectangle, and it will also clip if you try to
+ blit from areas outside the source bitmap. Example:
+
+ BITMAP *bmp;
+ ...
+ /* Blit src on the screen. */
+ blit(bmp, screen, 0, 0, 0, 0, bmp->w, bmp->h);
+
+ /* Now copy a chunk to a corner, slightly outside. /*
+ blit(screen, screen, 100, 100, -10, -10, 25, 30);
+
+ You can blit between any parts of any two bitmaps, even if the two memory
+ areas overlap (ie. source and dest are the same, or one is sub-bitmap of
+ the other). You should be aware, however, that a lot of SVGA cards don't
+ provide separate read and write banks, which means that blitting from one
+ part of the screen to another requires the use of a temporary bitmap in
+ memory, and is therefore extremely slow. As a general rule you should
+ avoid blitting from the screen onto itself in SVGA modes.
+
+
+ In mode-X, on the other hand, blitting from one part of the screen to
+ another can be significantly faster than blitting from memory onto the
+ screen, as long as the source and destination are correctly aligned with
+ each other. Copying between overlapping screen rectangles is slow, but if
+ the areas don't overlap, and if they have the same plane alignment (ie.
+ (source_x%4) == (dest_x%4)), the VGA latch registers can be used for a
+ very fast data transfer. To take advantage of this, in mode-X it is often
+ worth storing tile graphics in a hidden area of video memory (using a
+ large virtual screen), and blitting them from there onto the visible part
+ of the screen.
+
+
+ If the GFX_HW_VRAM_BLIT bit in the gfx_capabilities flag is set, the
+ current driver supports hardware accelerated blits from one part of the
+ screen onto another. This is extremely fast, so when this flag is set it
+ may be worth storing some of your more frequently used graphics in an
+ offscreen portion of the video memory.
+
+
+ Unlike most of the graphics routines, blit() allows the source and
+ destination bitmaps to be of different color depths, so it can be
+ used to convert images from one pixel format to another. In this
+ case, the behavior is affected by the COLORCONV_KEEP_TRANS and
+ COLORCONV_DITHER* flags of the current color conversion mode: see
+ set_color_conversion() for more information.
+
+
+
void stretch_blit(BITMAP *source, BITMAP *dest,
+ int source_x, source_y, source_width, source_height,
+ int dest_x, dest_y, dest_width, dest_height);
+ Like blit(), except it can scale images (so the source and destination
+ rectangles don't need to be the same size) and requires the source and
+ destination bitmaps to be of the same color depth. This routine doesn't
+ do as much safety checking as the regular blit(): in particular you must
+ take care not to copy from areas outside the source bitmap, and you
+ cannot blit between overlapping regions, ie. you must use different
+ bitmaps for the source and the destination. Moreover, the source must
+ be a memory bitmap. Example:
+
void masked_blit(BITMAP *source, BITMAP *dest, int source_x, int source_y,
+ int dest_x, int dest_y, int width, int height);
+ Like blit(), but skips transparent pixels, which are marked by a zero in
+ 256-color modes or bright pink for truecolor data (maximum red and blue,
+ zero green), and requires the source and destination bitmaps to be of
+ the same color depth. The source and destination regions must not overlap.
+ Example:
+
+ If the GFX_HW_VRAM_BLIT_MASKED bit in the gfx_capabilities flag is set,
+ the current driver supports hardware accelerated masked blits from one
+ part of the screen onto another. This is extremely fast, so when this
+ flag is set it may be worth storing some of your more frequently used
+ sprites in an offscreen portion of the video memory.
+
+
+ Warning: if the hardware acceleration flag is not set, masked_blit() will
+ not work correctly when used with a source image in system or video
+ memory so the latter must be a memory bitmap.
+
+
+
void masked_stretch_blit(BITMAP *source, BITMAP *dest,
+ int source_x, source_y, source_w, source_h,
+ int dest_x, dest_y, dest_w, dest_h);
+ Like masked_blit(), except it can scale images (so the source and
+ destination rectangles don't need to be the same size). This routine
+ doesn't do as much safety checking as the regular masked_blit(): in
+ particular you must take care not to copy from areas outside the source
+ bitmap. Moreover, the source must be a memory bitmap. Example:
+
+ Draws a copy of the sprite bitmap onto the destination bitmap at the
+ specified position. This is almost the same as blit(sprite, bmp, 0, 0, x,
+ y, sprite->w, sprite->h), but it uses a masked drawing mode where
+ transparent pixels are skipped, so the background image will show through
+ the masked parts of the sprite. Transparent pixels are marked by a zero
+ in 256-color modes or bright pink for truecolor data (maximum red and
+ blue, zero green). Example:
+
+ If the GFX_HW_VRAM_BLIT_MASKED bit in the gfx_capabilities flag is set,
+ the current driver supports hardware accelerated sprite drawing when the
+ source image is a video memory bitmap or a sub-bitmap of the screen. This
+ is extremely fast, so when this flag is set it may be worth storing some
+ of your more frequently used sprites in an offscreen portion of the video
+ memory.
+
+
+ Warning: if the hardware acceleration flag is not set, draw_sprite() will
+ not work correctly when used with a sprite image in system or video
+ memory so the latter must be a memory bitmap.
+
+
+ Although generally not supporting graphics of mixed color depths, as a
+ special case this function can be used to draw 256-color source images
+ onto truecolor destination bitmaps, so you can use palette effects on
+ specific sprites within a truecolor program.
+
+
+
+ Like draw_sprite(), except it can stretch the sprite image to the
+ specified width and height and requires the sprite image and destination
+ bitmap to be of the same color depth. Moreover, the sprite image must
+ be a memory bitmap. Example:
+
+ These are like draw_sprite(), but they additionally flip the image
+ vertically, horizontally, or both, respectively. Flipping vertically
+ means that the y-axis is reversed, while flipping horizontally means
+ that the x-axis is reversed, between the source and the destination.
+ This produces exact mirror images, which is not the same as rotating the
+ sprite (and it is a lot faster than the rotation routine). The sprite
+ must be a memory bitmap. Example:
+
+ Uses the global color_map table or truecolor blender functions to overlay
+ the sprite on top of the existing image. This must only be used after you
+ have set up the color mapping table (for 256-color modes) or blender
+ functions (for truecolor modes). Because it involves reading as well as
+ writing the bitmap memory, translucent drawing is very slow if you draw
+ directly to video RAM, so wherever possible you should use a memory
+ bitmap instead. Example:
+
+ The bitmap and sprite must normally be in the same color depth, but as a
+ special case you can draw 32 bit RGBA format sprites onto any hicolor or
+ truecolor bitmap, as long as you call set_alpha_blender() first, and you
+ can draw 8-bit alpha images onto a 32-bit RGBA destination, as long as you
+ call set_write_alpha_blender() first. As draw_sprite() this function skips
+ transparent pixels, except if the source sprite is an 8-bit image; if this
+ is the case, you should pay attention to properly set up your color map
+ table for index 0.
+
+
+
+ In 256-color modes, uses the global color_map table to tint the sprite
+ image to the specified color or to light it to the level specified by
+ 'color', depending on the function which was used to build the table
+ (create_trans_table or create_light_table), and draws the resulting image
+ to the destination bitmap. In truecolor modes, uses the blender functions
+ to light the sprite image using the alpha level specified by 'color' (the
+ alpha level which was passed to the blender functions is ignored) and
+ draws the resulting image to the destination bitmap. The 'color' parameter
+ must be in the range [0-255] whatever its actual meaning is. This must
+ only be used after you have set up the color mapping table (for 256-color
+ modes) or blender functions (for truecolor modes). Example:
+
+ /* Some one time initialisation code. */
+ COLOR_MAP global_light_table;
+ create_light_table(&global_trans_table, my_palette,
+ 10, 10, 60, NULL);
+ ...
+ if (get_color_depth() == 8)
+ color_map = &global_light_table;
+ else
+ set_trans_blender(40, 40, 255, 255);
+
+ /* Lit the cape with a blueish light. */
+ draw_lit_sprite(buffer, colored_cape, x, y);
+ More sophisticated version of draw_lit_sprite(): the 'color' parameter is
+ not constant across the sprite image anymore but interpolated between the
+ four specified corner colors. The corner values passed to this function
+ indicate the strength of the color applied on them, ranging from 0 (no
+ strength) to 255 (full strength). Example:
+
+ /* Some one time initialisation code. */
+ COLOR_MAP global_light_table;
+ create_light_table(&global_trans_table, my_palette,
+ 0, 0, 0, NULL);
+ ...
+ if (get_color_depth() == 8)
+ color_map = &global_light_table;
+ else
+ set_trans_blender(0, 0, 0, 128);
+
+ /* Enemies are in shadow unless lit by torch. */
+ draw_gouraud_sprite(buffer, menacing_spy, x, y,
+ light_strength_on_corner_1,
+ light_strength_on_corner_2,
+ light_strength_on_corner_3,
+ light_strength_on_corner_4);
+ Draws a copy of the sprite bitmap onto the destination bitmap at the
+ specified position, drawing transparent pixels in the background color
+ (or skipping them if the background color is -1) and setting all other
+ pixels to the specified color. Transparent pixels are marked by a zero
+ in 256-color modes or bright pink for truecolor data (maximum red and
+ blue, zero green). The sprite must be an 8-bit image, even if the
+ destination is a truecolor bitmap. Example:
+
+ Draws the sprite image onto the bitmap. It is placed with its top left
+ corner at the specified position, then rotated by the specified angle
+ around its centre. The angle is a fixed point 16.16 number in the same
+ format used by the fixed point trig routines, with 256 equal to a full
+ circle, 64 a right angle, etc. All rotation functions can draw between any
+ two bitmaps, even screen bitmaps or bitmaps of different color depth.
+
+
+ Positive increments of the angle will make the sprite rotate clockwise
+ on the screen, as demonstrated by the Allegro example.
+
+
+
+ Like rotate_sprite, but flips the image vertically before rotating it. To
+ flip horizontally, use this routine but add itofix(128) to the angle. To
+ flip in both directions, use rotate_sprite() and add itofix(128) to its
+ angle.
+
+
+
+ Like rotate_scaled_sprite(), but aligns the point in the sprite given by
+ (cx, cy) to (x, y) in the bitmap, then rotates and scales around this
+ point.
+
+
+
+ Like rotate_scaled_sprite_v_flip(), but aligns the point in the sprite
+ given by (cx, cy) to (x, y) in the bitmap, then rotates and scales around
+ this point.
+
+
+
+
+
get_rle_sprite — Creates an RLE sprite using a bitmap as source.
+
+
+
+Because bitmaps can be used in so many different ways, the bitmap structure
+is quite complicated, and it contains a lot of data. In many situations,
+though, you will find yourself storing images that are only ever copied to
+the screen, rather than being drawn onto or used as filling patterns, etc.
+If this is the case you may be better off storing your images in RLE_SPRITE
+(read chapter "Structures and types defined by Allegro" for an internal
+description of the RLE_SPRITE structure) or COMPILED_SPRITE (see next
+chapter) structures rather than regular bitmaps.
+
+
+RLE sprites store the image in a simple run-length encoded format, where
+repeated zero pixels are replaced by a single length count, and strings of
+non-zero pixels are preceded by a counter giving the length of the solid
+run. RLE sprites are usually much smaller than normal bitmaps, both because
+of the run length compression, and because they avoid most of the overhead
+of the bitmap structure. They are often also faster than normal bitmaps,
+because rather than having to compare every single pixel with zero to
+determine whether it should be drawn, it is possible to skip over a whole
+run of zeros with a single add, or to copy a long run of non-zero pixels
+with fast string instructions.
+
+
+Every silver lining has a cloud, though, and in the case of RLE sprites it
+is a lack of flexibility. You can't draw onto them, and you can't flip them,
+rotate them, or stretch them. In fact the only thing you can do with them is
+to blast them onto a bitmap with the draw_rle_sprite() function, which is
+equivalent to using draw_sprite() with a regular bitmap. You can convert
+bitmaps into RLE sprites at runtime, or you can create RLE sprite structures
+in grabber datafiles by making a new object of type 'RLE sprite'.
+
+
+ Creates an RLE sprite based on the specified bitmap (which must be a
+ memory bitmap). Remember to free this RLE sprite later to avoid memory
+ leaks. Example:
+
+ RLE_SPRITE *rle;
+ BITMAP *bmp;
+ ...
+ /* Create RLE sprite from an existent bitmap. */
+ rle = get_rle_sprite(bmp);
+ if (!rle)
+ abort_on_error("Couldn't create RLE sprite!");
+
+ /* We don't need the bitmap any more.*/
+ destroy_bitmap(bmp);
+
+ /* Use the RLE sprite. */
+ ...
+ /* Destroy it when we don't need it any more. */
+ destroy_rle_sprite(rle);
+
Return value:
+ Returns a pointer to the created RLE sprite, or NULL if the RLE sprite
+ could not be created. Remember to free this RLE sprite later to avoid
+ memory leaks.
+
+
+
+ Destroys an RLE sprite structure previously returned by get_rle_sprite().
+ If you pass a NULL pointer this function won't do anything. Use this once
+ you are done with an RLE sprite to avoid memory leaks in your program.
+
+
+
+ Translucent version of draw_rle_sprite(). See the description of
+ draw_trans_sprite(). This must only be used after you have set up the
+ color mapping table (for 256-color modes) or blender functions (for
+ truecolor modes). The bitmap and sprite must normally be in the same
+ color depth, but as a special case you can draw 32-bit RGBA format
+ sprites onto any hicolor or truecolor bitmap, as long as you call
+ set_alpha_blender() first. Example:
+
+ Tinted version of draw_rle_sprite(). See the description of
+ draw_lit_sprite(). This must only be used after you have set up the color
+ mapping table (for 256-color modes) or blender functions (for truecolor
+ modes). Example:
+
+ /* Some one time initialisation code. */
+ COLOR_MAP global_light_table;
+ create_light_table(&global_trans_table, my_palette,
+ 10, 10, 60, NULL);
+ ...
+ if (get_color_depth() == 8)
+ color_map = &global_light_table;
+ else
+ set_trans_blender(40, 40, 255, 255);
+
+ /* Lit the cape with a blueish light. */
+ draw_lit_rle_sprite(buffer, rle_colored_cape, x, y);
+Compiled sprites are stored as actual machine code instructions that draw a
+specific image onto a bitmap, using mov instructions with immediate data
+values. This is the fastest way to draw a masked image: on slow machines,
+up to and including a 486, drawing compiled sprites can be about to five
+times as fast as using draw_sprite() with a regular bitmap. On newer
+machines the difference is usually negligible.
+
+
+Compiled sprites are big, so if memory is tight you should use RLE sprites
+instead, and what you can do with them is even more restricted than with RLE
+sprites, because they don't support clipping. If you try to draw one off the
+edge of a bitmap, you will corrupt memory and probably crash the system. You
+can convert bitmaps into compiled sprites at runtime, or you can create
+compiled sprite structures in grabber datafiles by making a new object of
+type 'Compiled sprite' or 'Compiled x-sprite'.
+
+
+ Creates a compiled sprite based on the specified bitmap (which must be a
+ memory bitmap). Compiled sprites are device-dependent, so you have to
+ specify whether to compile it into a linear or planar format. Pass FALSE
+ as the second parameter if you are going to be drawing it onto memory
+ bitmaps or mode 13h and SVGA screen bitmaps, and pass TRUE if you are
+ going to draw it onto mode-X or Xtended mode screen bitmaps. Example:
+
+ COMPILED_SPRITE *cspr;
+ BITMAP *bmp;
+ ...
+ /* Create compiled sprite from an existent bitmap. */
+ cspr = get_compiled_sprite(bmp, 0);
+ if (!cspr)
+ abort_on_error("Couldn't create compiled sprite!");
+
+ /* We don't need the bitmap any more.*/
+ destroy_bitmap(bmp);
+
+ /* Use the compiled sprite. */
+ ...
+ /* Destroy it when we don't need it any more. */
+ destroy_compiled_sprite(cspr);
+
+ Returns a pointer to the created compiled sprite, or NULL if the compiled
+ sprite could not be created. Remember to free this compiled sprite later
+ to avoid memory leaks.
+
+
+
+ Destroys a compiled sprite structure previously returned by
+ get_compiled_sprite(). If you pass a NULL pointer this function won't do
+ anything. Use this once you are done with a compiled sprite to avoid
+ memory leaks in your program.
+
+
+
+ Draws a compiled sprite onto a bitmap at the specified position. The
+ sprite must have been compiled for the correct type of bitmap (linear or
+ planar). This function does not support clipping.
+
+
+ Hint: if not being able to clip compiled sprites is a problem, a neat
+ trick is to set up a work surface (memory bitmap, mode-X virtual screen,
+ or whatever) a bit bigger than you really need, and use the middle of it
+ as your screen. That way you can draw slightly off the edge without any
+ trouble...
+
+
+
+
+
+Allegro provides routines for loading fonts directly from GRX format .fnt
+files, 8x8 or 8x16 BIOS format .fnt files, from bitmap images, from datafiles
+or you can import a multiple-range Unicode font by writing a .txt script that
+specifies a number of different source files for each range of characters.
+
+
+By default, Allegro can only use bitmapped (non-scalable) fonts. If you want
+to use TrueType fonts, you will need to use an add-on library which allows
+you to load them on the fly (like AllegTTF or Glyph Keeper, listed among
+others at http://www.allegro.cc/) and render them directly, or generate a
+bitmapped version of a TrueType font with tools like TTF2PCX
+(http://www.talula.demon.co.uk/ttf2pcx/index.html).
+
+
+ Informs the load_font() functions of a new file type, providing a routine
+ to read fonts in this format. The function you supply must follow the
+ following prototype:
+
+ The pal parameter can optionally be used to return a palette for the FONT.
+ The parameter param can be anything you like: you can use this to pass
+ information to your loading routine, such as for instance the font height,
+ the character range to load or the index number of a font in a datafile.
+ If you choose to write your own font loading code, your function should be
+ prepared to deal with a value of NULL for either of these parameters.
+
+
+
+ Loads a font from a file. At present, this supports loading fonts from
+ a GRX format .fnt file, a 8x8 or 8x16 BIOS format .fnt file, a datafile or
+ any bitmap format that can be loaded by load_bitmap().
+
+
+ If the font contains palette information, then the palette is returned in
+ the second parameter, which should be an array of 256 RGB structures
+ (a PALETTE). The pal argument may be NULL. In this case, the palette data,
+ if present, is simply not returned.
+
+
+ The third parameter can be used to pass specific information to a custom
+ loader routine. Normally, you can just leave this as NULL. Note that
+ another way of loading fonts is embedding them into a datafile and using
+ the datafile related functions.
+
+
Return value:
+ Returns a pointer to the font or NULL on error. Remember that you are
+ responsible for destroying the font when you are finished with it to
+ avoid memory leaks.
+
+
+
+ Frees the memory being used by a font structure. Don't use this on the
+ default global Allegro font or any text routines using it could crash. You
+ should use this only on fonts you have loaded manually after you are done
+ with them, to prevent memory leaks in your program.
+
+
+
+ This function converts a font to use transparency for drawing. That is, each
+ glyph in the font will be drawn with draw_trans_sprite, so you can use the
+ same blenders as with draw_trans_sprite to draw the font. One common use of
+ this is to load a bitmap font with an alpha channel, and therefore get
+ anti-aliased text output by using Allegro's alpha blender. Here's an example
+ how to do that:
+
+
+ Use this function to find out the number of character ranges in a font. You
+ should query each of these ranges with get_font_range_begin() and
+ get_font_range_end() to find out what characters are available in the
+ font. Example:
+
+ FONT *f;
+ int range;
+ int n;
+ ...
+
+ range = get_font_ranges(f);
+ printf("The font has %d character ranges:\n", range);
+ for (n = 0; n < range; n++)
+ printf("Range %d from 0x%03x - 0x%03x\n",
+ get_font_range_begin(f, n),
+ get_font_range_end(f, n));
+
Return value:
+ Returns the number of continuous character ranges in a font, or -1 if that
+ information is not available.
+
+
+
+ This function allows you to find out the start of a specific character
+ range for a font. You can pass -1 for the `range' parameter if you want to
+ know the start of the whole font range, or a number from 0 to (but not
+ including) get_font_ranges(f) to get the start of a specific character
+ range in the font. Example:
+
+ This function allows you to find out the index to the last character of a
+ character range for a font. You can pass -1 for the range parameter if you
+ want to know the start of the whole font range, or a number from 0 to (but
+ not including) get_font_ranges(f) to get the start of a specific character
+ range in the font. You should check the start and end of all font ranges to
+ see if a specific character is actually available in the font. Not all
+ characters in the range returned by get_font_range_begin(f, -1) and
+ get_font_range_end(f, -1) need to be available! Example:
+
+ This function extracts a character range from a font and returns a new font
+ that contains only the range of characters selected by this function. You
+ can pass -1 for either the lower or upper bound if you want to select all
+ characters from the start or to the end of the font.
+ Example:
+
Return value:
+ Returns a pointer to the new font or NULL on error. Remember that you are
+ responsible for destroying the font when you are finished with it to
+ avoid memory leaks.
+
+
+
+ This function transposes all characters in a font, effectively remapping the
+ font. Example:
+
+ FONT *myfont;
+ FONT *capitals;
+ ...
+ /* Create a font of only capital letters */
+ capitals = extract_font_range(myfont, 'A', 'Z');
+
+ /* Now transpose the characters in the font so that they will be used */
+ /* for the lower case letters a-z */
+ transpose_font(capitals, 'a'-'A');
+ textout_ex(screen, capitals, "allcaps",
+ 100, 100, makecol(255,255,255), 0);
+
Return value:
+ Returns 0 on success, -1 on failure.
+
+
+
+ This function merges the character ranges from two fonts and returns a new
+ font containing all characters in the old fonts. In general, you cannot
+ merge fonts of different types (eg, TrueType fonts and bitmapped fonts),
+ but as a special case, this function can promote a monochrome bitmapped
+ font to a color font and merge those. Example:
+
+ FONT *myfont;
+ FONT *myfancy_font;
+ FONT *lower_range;
+ FONT *upper_range;
+ FONT *capitals;
+ FONT *combined_font;
+ FONT *tempfont;
+ ...
+ /* Create a font that contains the capatials from */
+ /* the fancy font but other characters from myfont */
+ lower_range = extract_font_range(myfont, -1, 'A'-1);
+ upper_range = extract_font_range(myfont, 'Z'+1, -1);
+ capitals = extract_font_range(myfancy_font, 'A', 'Z');
+
+ tempfont = merge_fonts(lower_range, capitals);
+ combined_font = merge_fonts(tempfont, upper_range);
+
+ /* Clean up temporary fonts */
+ destroy_font(lower_range);
+ destroy_font(upper_range);
+ destroy_font(capitals);
+ destroy_font(tempfont);
+
Return value:
+ Returns a pointer to the new font or NULL on error. Remember that you are
+ responsible for destroying the font when you are finished with it to
+ avoid memory leaks.
+
+
+
+ Loads a FONT from an Allegro datafile. You can set param parameter to
+ point to an array that holds two strings that identify the font and the
+ palette in the datafile by name.
+ The first string in this list is the name of the font. You can pass NULL
+ here to just load the first font found in the datafile. The second string
+ can be used to specify the name of the palette associated with the font.
+ This is only returned if the pal parameter is not NULL. If you pass NULL
+ for the name of the palette, the last palette found before the font was
+ found is returned.
+ You can also pass NULL for param, which is treated as if you had passed
+ NULL for both strings separately. In this case, the function will simply
+ load the first font it finds from the datafile and the palette that
+ precedes it.
+
+
+ For example, suppose you have a datafile named `fonts.dat' with the
+ following contents:
+
+ FONT FONT_1_DATA
+ FONT FONT_2_DATA
+ FONT FONT_3_DATA
+ PAL FONT_1_PALETTE
+ PAL FONT_2_PALETTE
+
+ Then the following code will load FONT_1_DATA as a FONT and return
+ FONT_1_PALETTE as the palette:
+
+ If you want to load the third font, but not bother with a palette, use:
+
+ FONT *f;
+ char *names[] = { "FONT_3_DATA", NULL }
+
+ f = load_dat_font("fonts.dat", NULL, names);
+
Return value:
+ Returns a pointer to the font or NULL on error. Remember that you are
+ responsible for destroying the font when you are finished with it to
+ avoid memory leaks.
+
+
+
+ Loads a 8x8 or 8x16 BIOS format font. You shouldn't normally call this
+ routine directly.
+
Return value:
+ Returns a pointer to the font or NULL on error. Remember that you are
+ responsible for destroying the font when you are finished with it to
+ avoid memory leaks.
+
+
+
+ Loads a GRX format font. You shouldn't normally call this routine
+ directly.
+
Return value:
+ Returns a pointer to the font or NULL on error. Remember that you are
+ responsible for destroying the font when you are finished with it to
+ avoid memory leaks.
+
+
+
+ Loads either a BIOS or GRX format font. You shouldn't normally call this
+ routine directly.
+
Return value:
+ Returns a pointer to the font or NULL on error. Remember that you are
+ responsible for destroying the font when you are finished with it to
+ avoid memory leaks.
+
+
+
+ Tries to grab a font from a bitmap. The bitmap can be in any format that
+ load_bitmap understands.
+
+
+ The size of each character is determined by the layout of the image, which
+ should be a rectangular grid containing all the ASCII characters from
+ space (32) up to the tilde (126). The way the characters are separated
+ depends on the colordepth of the image file:
+
+ paletted (8 bit) image file
+ Use color 0 for the transparent portions of the characters and fill the
+ spaces between each letter with color 255.
+
+ High (15/16 bit) and true (24/32 bit) color image file
+ Use bright pink (maximum red and blue, zero green) for the transparent
+ portions of the characters and fill the spaces between each letter with
+ bright yellow (maximum red and green, zero blue).
+
+
+
+ Note that in each horizontal row the bounding boxes around the characters
+ should align and have the same height.
+
+
+ Probably the easiest way to get to grips with how this works is to load up
+ the `demo.dat' file and export the TITLE_FONT into a PCX file. Have a look
+ at the resulting picture in your paint program: that is the format a font
+ should be in.
+
+
+ Take care with high and true color fonts: Allegro will convert these to the
+ current colordepth when you load the font. If you try to use a font on
+ a bitmap with a different color depth Allegro will do color conversions on
+ the fly, which will be rather slow. For optimal performance you should
+ set the colordepth to the colordepth you want to use before loading any
+ fonts.
+
Return value:
+ Returns a pointer to the font or NULL on error. Remember that you are
+ responsible for destroying the font when you are finished with it to
+ avoid memory leaks.
+
+
+
+ This function is the work-horse of load_bitmap_font, and can be used to
+ grab a font from a bitmap in memory. You can use this if you want to
+ generate or modify a font at runtime. The bitmap should follow the layout
+ described for load_bitmap_font.
+
Return value:
+ Returns a pointer to the font or NULL on error. Remember that you are
+ responsible for destroying the font when you are finished with it to
+ avoid memory leaks.
+
+
+
+ This function can be used to load scripted fonts. The script file
+ contains a number of lines in the format "filename start end", which
+ specify the source file for that range of characters, the Unicode value of
+ the first character in the range, and the end character in the range
+ (optional, if left out, the entire input file will be grabbed). If the
+ filename is replaced by a hyphen, more characters will be grabbed from the
+ previous input file.
+ For example, the script:
+
+ would import the first 96 characters from ascii.fnt as the range
+ 0x20-0x7F, the next 96 characters from ascii.fnt as the range 0xA0-0xFF,
+ and the entire contents of dingbats.fnt starting at Unicode position
+ 0x1000.
+
Return value:
+ Returns a pointer to the font or NULL on error. Remember that you are
+ responsible for destroying the font when you are finished with it to
+ avoid memory leaks.
+
+
+
+
+
+Allegro provides text output routines that work with both monochrome and
+color fonts, which can contain any number of Unicode character ranges. The
+grabber program can create fonts from sets of characters drawn in a bitmap
+file (see grabber.txt for more information), and can also import GRX or BIOS
+format font files. The font structure contains a number of hooks that can be
+used to extend it with your own custom drawing code: see the definition in
+allegro/text.h for details.
+
+
+ A simple 8x8 fixed size font (the mode 13h BIOS default). If you want to
+ alter the font used by the GUI routines, change this to point to one of
+ your own fonts. This font contains the standard ASCII (U+20 to U+7F),
+ Latin-1 (U+A1 to U+FF), and Latin Extended-A (U+0100 to U+017F) character
+ ranges.
+
+
+
+ When Allegro cannot find a glyph it needs in a font, it will instead
+ output the character given in allegro_404_char. By default, this is set to
+ the caret symbol, `^', but you can change this global to use any other
+ character instead. Example:
+
+ /* Show unknown glyphs with an asterisk. */
+ allegro_404_char = '*';
void textout_ex(BITMAP *bmp, const FONT *f, const char *s,
+ int x, int y, int color, int bg);
+ Writes the string `s' onto the bitmap at position x, y, using the
+ specified font, foreground color and background color. If the background
+ color is -1, then the text is written transparently. If the foreground
+ color is -1 and a color font is in use, it will be drawn using the colors
+ from the original font bitmap (the one you imported into the grabber
+ program), which allows multicolored text output. For high and true color
+ fonts, the foreground color is ignored and always treated as -1. Example:
+
+ /* Show the program's version in blue letters. */
+ textout_ex(screen, font, "v4.2.0-beta2", 10, 10,
+ makecol(0, 0, 255), -1);
void textout_justify_ex(BITMAP *bmp, const FONT *f, const char *s,
+ int x1, int x2, int y, int diff, int color,
+ int bg);
+ Draws justified text within the region x1-x2. If the amount of spare
+ space is greater than the diff value, it will give up and draw regular
+ left justified text instead. Example:
+
+ char *lines[] = {"Draws justified text",
+ "within the specified",
+ "x2-x1 area. But not",
+ "T H I S !", NULL};
+ /* Show the justification marker. */
+ vline(screen, 200, 0, SCREEN_H-1, makecol(0, 0, 0));
+ /* Draw all the lines until we reach a NULL entry. */
+ for (num = 0, y = 0; lines[num]; num++, y += text_height(font))
+ textout_justify_ex(screen, font, lines[num], 0, 200,
+ y, 80, makecol(0, 0, 0),
+ makecol(255, 255, 255));
void textprintf_ex(BITMAP *bmp, const FONT *f, int x, int y,
+ int color, int bg, const char *fmt, ...);
+ Formatted text output, using a printf() style format string. Due to an
+ internal limitation, this function can't be used for extremely long texts.
+ If you happen to reach this limit, you can work around it by using
+ uszprintf() and textout_ex(), which don't have any. Example:
+
+ Like textprintf_ex(), but interprets the x coordinate as the centre rather
+ than the left edge of the string. This function shares the text length
+ limitation of textprintf_ex(). Example:
+
+ Like textprintf_ex(), but interprets the x coordinate as the right rather
+ than the left edge of the string. This function shares the text length
+ limitation of textprintf_ex(). Example:
+
+ Like textout_justify_ex(), but using a printf() style format string. This
+ function shares the text length limitation of textprintf_ex(). Example:
+
+ char *lines[] = {"Line %02d: Draws justified text",
+ "Line %02d: within the specified",
+ "Line %02d: x2-x1 area. But not",
+ "Line %02d: T H I S !", NULL};
+ /* Show the justification marker. */
+ vline(screen, 300, 0, SCREEN_H-1, makecol(0, 0, 0));
+ /* Draw all the lines until we reach a NULL entry. */
+ for (num = 0, y = 0; lines[num]; num++, y += text_height(font))
+ textprintf_justify_ex(screen, font, 0, 300, y, 180,
+ makecol(0, 0, 0), makecol(255, 255, 255),
+ lines[num], num);
set_zbuffer — Makes the given Z-buffer the active one.
+
triangle3d — Draws a 3d triangle onto the specified bitmap.
+
triangle3d_f — Draws a 3d triangle onto the specified bitmap.
+
+
+
+All the 3d functions that accept a `type' parameter are asking for a polygon
+rendering mode, which can be any of the following POLYTYPE_* values. If the
+CPU_MMX flag of the cpu_capabilities global variable is set, the GRGB and
+truecolor *LIT routines will be optimised using MMX instructions. If the
+CPU_3DNOW flag is set, the truecolor PTEX*LIT routines will take advantage of
+the 3DNow! CPU extensions.
+
+
+Using MMX for *LIT routines has a side effect: normally (without MMX), these
+routines use the blender functions used also for other lighting functions,
+set with set_trans_blender() or set_blender_mode(). The MMX versions only use
+the RGB value passed to set_trans_blender() and do the linear interpolation
+themselves. Therefore a new set of blender functions passed to
+set_blender_mode() is ignored.
+
+
+ A simple flat shaded polygon, taking the color from the `c' value of the
+ first vertex. This polygon type is affected by the drawing_mode() function,
+ so it can be used to render XOR or translucent polygons.
+
+
+
+ A single-color gouraud shaded polygon. The colors for each vertex are taken
+ from the `c' value, and interpolated across the polygon. This is very fast,
+ but will only work in 256-color modes if your palette contains a smooth
+ gradient between the colors. In truecolor modes it interprets the color as
+ a packed, display-format value as produced by the makecol() function.
+
+
+
+ A gouraud shaded polygon which interpolates RGB triplets rather than a
+ single color. In 256-color modes this uses the global rgb_map table to
+ convert the result to an 8-bit paletted color, so it must only be used
+ after you have set up the RGB mapping table! The colors for each vertex are
+ taken from the `c' value, which is interpreted as a 24-bit RGB triplet
+ (0xFF0000 is red, 0x00FF00 is green, and 0x0000FF is blue).
+
+
+
+ An affine texture mapped polygon. This stretches the texture across the
+ polygon with a simple 2d linear interpolation, which is fast but not
+ mathematically correct. It can look ok if the polygon is fairly small or
+ flat-on to the camera, but because it doesn't deal with perspective
+ foreshortening, it can produce strange warping artifacts. To see what this
+ means, run Allegro's test program and see what happens to the polygon3d()
+ test when you zoom in very close to the cube.
+
+
+
+ A perspective-correct texture mapped polygon. This uses the `z' value from
+ the vertex structure as well as the u/v coordinates, so textures are
+ displayed correctly regardless of the angle they are viewed from. Because
+ it involves division calculations in the inner texture mapping loop, this
+ mode is a lot slower than POLYTYPE_ATEX, and it uses floating point so it
+ will be very slow on anything less than a Pentium (even with an FPU, a 486
+ can't overlap floating point division with other integer operations like
+ the Pentium can).
+
+
+
+ Like POLYTYPE_ATEX and POLYTYPE_PTEX, but the global color_map table (for
+ 256-color modes) or blender function (for non-MMX truecolor modes) is used
+ to blend the texture with a light level taken from the `c' value in the
+ vertex structure. This must only be used after you have set up the color
+ mapping table or blender functions!
+
+
+
+ Render translucent textures. All the general rules for drawing
+ translucent things apply. However, these modes have a major
+ limitation: they only work with memory bitmaps or linear frame
+ buffers (not with banked frame buffers). Don't even try, they do not
+ check and your program will die horribly (or at least draw wrong
+ things).
+
+
+
+ Draw 3d polygons onto the specified bitmap, using the specified rendering
+ mode. Unlike the regular polygon() function, these routines don't support
+ concave or self-intersecting shapes, and they can't draw onto mode-X
+ screen bitmaps (if you want to write 3d code in mode-X, draw onto a
+ memory bitmap and then blit to the screen). The width and height of the
+ texture bitmap must be powers of two, but can be different, eg. a 64x16
+ texture is fine, but a 17x3 one is not. The vertex count parameter (vc)
+ should be followed by an array containing the appropriate number of
+ pointers to vertex structures: polygon3d() uses the fixed point V3D
+ structure, while polygon3d_f() uses the floating point V3D_f structure.
+ These are defined as:
+
+ typedef struct V3D
+ {
+ fixed x, y, z; - position
+ fixed u, v; - texture map coordinates
+ int c; - color
+ } V3D;
+
+ typedef struct V3D_f
+ {
+ float x, y, z; - position
+ float u, v; - texture map coordinates
+ int c; - color
+ } V3D_f;
+
+ How the vertex data is used depends on the rendering mode:
+
+
+ The `x' and `y' values specify the position of the vertex in 2d screen
+ coordinates.
+
+
+ The `z' value is only required when doing perspective correct texture
+ mapping, and specifies the depth of the point in 3d world coordinates.
+
+
+ The `u' and `v' coordinates are only required when doing texture mapping,
+ and specify a point on the texture plane to be mapped on to this vertex.
+ The texture plane is an infinite plane with the texture bitmap tiled
+ across it. Each vertex in the polygon has a corresponding vertex on the
+ texture plane, and the image of the resulting polygon in the texture plane
+ will be mapped on to the polygon on the screen.
+
+
+ We refer to pixels in the texture plane as texels. Each texel is a block,
+ not just a point, and whole numbers for u and v refer to the top-left
+ corner of a texel. This has a few implications. If you want to draw a
+ rectangular polygon and map a texture sized 32x32 on to it, you would use
+ the texture coordinates (0,0), (0,32), (32,32) and (32,0), assuming the
+ vertices are specified in anticlockwise order. The texture will then be
+ mapped perfectly on to the polygon. However, note that when we set u=32,
+ the last column of texels seen on the screen is the one at u=31, and the
+ same goes for v. This is because the coordinates refer to the top-left
+ corner of the texels. In effect, texture coordinates at the right and
+ bottom on the texture plane are exclusive.
+
+
+ There is another interesting point here. If you have two polygons side
+ by side sharing two vertices (like the two parts of folded piece of
+ cardboard), and you want to map a texture across them seamlessly, the
+ values of u and v on the vertices at the join will be the same for both
+ polygons. For example, if they are both rectangular, one polygon may use
+ (0,0), (0,32), (32,32) and (32,0), and the other may use (32,0), (32,32),
+ (64,32), (64,0). This would create a seamless join.
+
+
+ Of course you can specify fractional numbers for u and v to indicate a
+ point part-way across a texel. In addition, since the texture plane is
+ infinite, you can specify larger values than the size of the texture.
+ This can be used to tile the texture several times across the polygon.
+
+
+ The `c' value specifies the vertex color, and is interpreted differently
+ by various rendering modes. Read the beginning of chapter "Polygon
+ rendering" for a list of rendering types you can use with this function.
+
+
+
+ Draw 3d triangles, using either fixed or floating point vertex structures.
+ Unlike quad3d[_f](), triangle3d[_f]() functions are not wrappers of
+ polygon3d[_f](). The triangle3d[_f]() functions use their own routines
+ taking into account the constantness of the gradients. Therefore
+ triangle3d[_f](bmp, type, tex, v1, v2, v3) is faster than
+ polygon3d[_f](bmp, type, tex, 3, v[]).
+
+
+ Read the beginning of chapter "Polygon rendering" for a list of rendering
+ types you can use with this function.
+
+
+
+ Draw 3d quads, using either fixed or floating point vertex structures.
+ These are equivalent to calling polygon3d(bmp, type, tex, 4, v[]) or
+ polygon3d_f(bmp, type, tex, 4, v[]).
+
+
+ Read the beginning of chapter "Polygon rendering" for a list of rendering
+ types you can use with this function.
+
+
+
int clip3d_f(int type, float min_z, float max_z, int vc,
+ const V3D_f *vtx[], V3D_f *vout[], V3D_f *vtmp[], int out[]);
+ Clips the polygon given in `vtx'. The number of vertices is `vc', the
+ result goes in `vout', and `vtmp' and `out' are needed for internal
+ purposes. The pointers in `vtx', `vout' and `vtmp' must point to valid
+ V3D_f structures.
+
+
+ As additional vertices may appear in the process of clipping, so the
+ size of `vout', `vtmp' and `out' should be at least vc * (1.5 ^ n), where
+ `n' is the number of clipping planes (5 or 6), and `^' denotes "to the
+ power of".
+
+
+ The frustum (viewing volume) is defined by -z<x<z, -z<y<z,
+ 0<min_z<z<max_z. If max_z<=min_z, the z<max_z clipping is
+ not done. As you can see, clipping is done in the camera space, with
+ perspective in mind, so this routine should be called after you apply
+ the camera matrix, but before the perspective projection. The routine
+ will correctly interpolate u, v, and c in the vertex structure. However,
+ no provision is made for high/truecolor GCOL.
+
Return value:
+ Returns the number of vertices after clipping is done.
+
+
+
int clip3d(int type, fixed min_z, fixed max_z, int vc,
+ const V3D *vtx[], V3D *vout[], V3D *vtmp[], int out[]);
+ Fixed point version of clip3d_f(). This function should be used with
+ caution, due to the limited precision of fixed point arithmetic and high
+ chance of rounding errors: the floating point code is better for most
+ situations.
+
Return value:
+ Returns the number of vertices after clipping is done.
+
+
+
+A Z-buffer stores the depth of each pixel that is drawn on a viewport.
+When a 3D object is rendered, the depth of each of its pixels is compared
+against the value stored into the Z-buffer: if the pixel is closer it is
+drawn, otherwise it is skipped.
+
+
+No polygon sorting is needed. However, backface culling should be done
+because it prevents many invisible polygons being compared against the
+Z-buffer. Z-buffered rendering is the only algorithm supported by Allegro
+that directly solves penetrating shapes (see example exzbuf.c, for instance).
+The price to pay is more complex (and slower) routines.
+
+
+Z-buffered polygons are designed as an extension of the normal POLYTYPE_*
+rendering styles. Just OR the POLYTYPE with the value POLYTYPE_ZBUF, and
+the normal polygon3d(), polygon3d_f(), quad3d(), etc. functions will
+render z-buffered polygons.
+
+
+Of course, the z coordinates have to be valid regardless of rendering style.
+
+
+A Z-buffered rendering procedure looks like a double-buffered rendering
+procedure. You should follow four steps: create a Z-buffer at the beginning
+of the program and make the library use it by calling set_zbuffer(). Then,
+for each frame, clear the Z-buffer and draw polygons with
+POLYTYPE_* | POLYTYPE_ZBUF and finally destroy the Z-buffer when leaving the
+program.
+
+
+Notes on Z-buffered renderers:
+
+Unlike the normal POLYTYPE_FLAT renderers, the Z-buffered ones don't use
+the hline() routine. Therefore DRAW_MODE has no effect.
+
+The *LIT* routines work the traditional way - through the set of
+blender routines.
+
+All the Z-buffered routines are much slower than their normal counterparts
+(they all use the FPU to interpolate and test 1/z values).
+
+ Creates a Z-buffer using the size of the BITMAP you are planning to draw
+ on. Several Z-buffers can be defined but only one can be used at the same
+ time, so you must call set_zbuffer() to make this Z-buffer active.
+
Return value:
+ Returns the pointer to the ZBUFFER or NULL if there was an error. Remember
+ to destroy the ZBUFFER once you are done with it, to avoid having memory
+ leaks.
+
+
+
+ Creates a sub-z-buffer, ie. a z-buffer sharing drawing memory with a
+ pre-existing z-buffer, but possibly with a different size. The same rules
+ as for sub-bitmaps apply: the sub-z-buffer width and height can extend
+ beyond the right and bottom edges of the parent (they will be clipped),
+ but the origin point must lie within the parent region.
+
+
+ When drawing z-buffered to a bitmap, the top left corner of the bitmap is
+ always mapped to the top left corner of the current z-buffer. So this
+ function is primarily useful if you want to draw to a sub-bitmap and use
+ the corresponding sub-area of the z-buffer. In other cases, eg. if you
+ just want to draw to a sub-bitmap of screen (and not to other parts of
+ screen), then you would usually want to create a normal z-buffer (not
+ sub-z-buffer) the size of the visible screen. You don't need to first
+ create a z-buffer the size of the virtual screen and then a sub-z-buffer
+ of that.
+
Return value:
+ Returns the pointer to the sub ZBUFFER or NULL if there was an error.
+ Remember to destroy the ZBUFFER once you are done with it, to avoid having
+ memory leaks.
+
+
+
+ Writes z into the given Z-buffer (0 means far away). This function should
+ be used to initialize the Z-buffer before each frame. Actually, low-level
+ routines compare depth of the current pixel with 1/z: for example, if you
+ want to clip polygons farther than 10, you must call
+ clear_zbuffer(zbuf, 0.1).
+
+
+
+Allegro provides two simple approaches to remove hidden surfaces:
+
+ Z-buffering - (see above)
+
+ Scan-line algorithms - along each scanline on your screen, you keep
+ track of what polygons you are "in" and which is the nearest. This
+ status changes only where the scanline crosses some polygon edge. So you
+ have to juggle an edge list and a polygon list. And you have to sort the
+ edges for each scanline (this can be countered by keeping the order of
+ the previous scanline - it won't change much). The BIG advantage is that
+ you write each pixel only once. If you have a lot of overlapping
+ polygons you can get incredible speeds compared to any of the previous
+ algorithms. This algorithm is covered by the *_scene routines.
+
+
+
+The scene rendering has approximately the following steps:
+
+ Initialize the scene (set the clip area, clear the bitmap, blit a
+ background, etc.)
+
+ Call clear_scene().
+
+ Transform all your points to camera space.
+
+ Clip polygons.
+
+ Project with persp_project() or persp_project_f().
+
+ "Draw" polygons with scene_polygon3d() and/or scene_polygon3d_f().
+ This doesn't do any actual drawing, only initializes tables.
+
+ Render all the polygons defined previously to the bitmap with
+ render_scene().
+
+ Overlay some non-3D graphics.
+
+ Show the bitmap (blit it to screen, flip the page, etc).
+
+
+
+For each horizontal line in the viewport an x-sorted edge list is used to
+keep track of what polygons are "in" and which is the nearest. Vertical
+coherency is used - the edge list for a scanline is sorted starting from
+the previous one - it won't change much. The scene rendering routines use
+the same low-level asm routines as normal polygon3d().
+
+
+Notes on scene rendering:
+
+ Unlike polygon3d(), scene_polygon3d() requires valid z coordinates
+ for all vertices, regardless of rendering style (unlike
+ polygon3d(), which only uses z coordinate for *PTEX*).
+
+ All polygons passed to scene_polygon3d() have to be
+ persp_project()'ed.
+
+ After render_scene() the mode is reset to SOLID.
+
+Using a lot of *MASK* polygons drastically reduces performance, because
+when a MASKed polygon is the first in line of sight, the polygons
+underneath have to be drawn too. The same applies to FLAT polygons drawn
+with DRAW_MODE_TRANS.
+
+
+Z-buffered rendering works also within the scene renderer. It may be
+helpful when you have a few intersecting polygons, but most of the
+polygons may be safely rendered by the normal scanline sorting algo.
+Same as before: just OR the POLYTYPE with POLYTYPE_ZBUF. Also, you
+have to clear the z-buffer at the start of the frame. Example:
+
+ clear_scene(buffer);
+ if (some_polys_are_zbuf) clear_zbuffer(0.);
+ while (polygons) {
+ ...
+ if (this_poly_is_zbuf) type |= POLYTYPE_ZBUF;
+ scene_polygon3d(type, tex, vc, vtx);
+ }
+ render_scene();
+ Allocates memory for a scene, `nedge' and `npoly' are your estimates of how
+ many edges and how many polygons you will render (you cannot get over the
+ limit specified here). If you use same values in succesive calls, the
+ space will be reused (no new malloc()).
+
+
+ The memory allocated is a little less than 150 * (nedge + npoly) bytes.
+
Return value:
+ Returns zero on success, or a negative number if allocations fail.
+
+
+
+ Puts a polygon in the rendering list. Nothing is really rendered at this
+ moment. Should be called between clear_scene() and render_scene().
+
+
+ Arguments are the same as for polygon3d(), except the bitmap is missing.
+ The one passed to clear_scene() will be used.
+
+
+ Unlike polygon3d(), the polygon may be concave or self-intersecting.
+ Shapes that penetrate one another may look OK, but they are not really
+ handled by this code.
+
+
+ Note that the texture is stored as a pointer only, and you should keep
+ the actual bitmap around until render_scene(), where it is used.
+
+
+ Since the FLAT style is implemented with the low-level hline() funtion,
+ the FLAT style is subject to DRAW_MODEs. All these modes are valid. Along
+ with the polygon, this mode will be stored for the rendering moment, and
+ also all the other related variables (color_map pointer, pattern pointer,
+ anchor, blender values).
+
+
+ The settings of the CPU_MMX and CPU_3DNOW flags of the cpu_capabilities
+ global variable on entry in this routine affect the choice of low-level
+ asm routine that will be used by render_scene() for this polygon.
+
Return value:
+ Returns zero on success, or a negative number if it won't be rendered for
+ lack of a rendering routine.
+
+
+
+ Renders all the specified scene_polygon3d()'s on the bitmap passed to
+ clear_scene(). Rendering is done one scanline at a time, with no pixel
+ being processed more than once.
+
+
+ Note that between clear_scene() and render_scene() you shouldn't change
+ the clip rectangle of the destination bitmap. For speed reasons, you
+ should set the clip rectangle to the minimum.
+
+
+ Note also that all the textures passed to scene_polygon3d() are stored as
+ pointers only and actually used in render_scene().
+
+
+
+ This number (default value = 100.0) controls the behaviour of the
+ z-sorting algorithm. When an edge is very close to another's polygon
+ plane, there is an interval of uncertainty in which you cannot tell which
+ object is visible (which z is smaller). This is due to cumulative
+ numerical errors for edges that have undergone a lot of transformations
+ and interpolations.
+
+
+ The default value means that if the 1/z values (in projected space)
+ differ by only 1/100 (one percent), they are considered to be equal and
+ the x-slopes of the planes are used to find out which plane is getting
+ closer when we move to the right.
+
+
+ Larger values means narrower margins, and increasing the chance of
+ missing true adjacent edges/planes. Smaller values means larger margins,
+ and increasing the chance of mistaking close polygons for adjacent ones.
+ The value of 100 is close to the optimum. However, the optimum shifts
+ slightly with resolution, and may be application-dependent. It is here
+ for you to fine-tune.
+
+
+
+
+
solid_mode — Shortcut for selecting solid drawing mode.
+
xor_mode — Shortcut for toggling xor drawing mode on and off.
+
+
+
+
void drawing_mode(int mode, BITMAP *pattern, int x_anchor, int y_anchor);
+ Sets the graphics drawing mode. This only affects the geometric routines
+ like putpixel, lines, rectangles, circles, polygons, floodfill, etc, not
+ the text output, blitting, or sprite drawing functions. The mode should
+ be one of the following constants:
+
+ DRAW_MODE_SOLID - the default, solid color
+ drawing
+ DRAW_MODE_XOR - exclusive-or drawing
+ DRAW_MODE_COPY_PATTERN - multicolored pattern fill
+ DRAW_MODE_SOLID_PATTERN - single color pattern fill
+ DRAW_MODE_MASKED_PATTERN - masked pattern fill
+ DRAW_MODE_TRANS - translucent color blending
+
+ In DRAW_MODE_SOLID, pixels of the bitmap being drawn onto are simply
+ replaced by those produced by the drawing function.
+
+
+ In DRAW_MODE_XOR, pixels are written to the bitmap with an exclusive-or
+ operation rather than a simple copy, so drawing the same shape twice will
+ erase it. Because it involves reading as well as writing the bitmap
+ memory, xor drawing is a lot slower than the normal replace mode.
+
+
+ With the patterned modes, you provide a pattern bitmap which is tiled
+ across the surface of the shape. Allegro stores a pointer to this bitmap
+ rather than copying it, so you must not destroy the bitmap while it is
+ still selected as the pattern. The width and height of the pattern must
+ be powers of two, but they can be different, eg. a 64x16 pattern is fine,
+ but a 17x3 one is not. The pattern is tiled in a grid starting at point
+ (x_anchor, y_anchor). Normally you should just pass zero for these
+ values, which lets you draw several adjacent shapes and have the patterns
+ meet up exactly along the shared edges. Zero alignment may look peculiar
+ if you are moving a patterned shape around the screen, however, because
+ the shape will move but the pattern alignment will not, so in some
+ situations you may wish to alter the anchor position.
+
+
+ When you select DRAW_MODE_COPY_PATTERN, pixels are simply copied from the
+ pattern bitmap onto the destination bitmap. This allows the use of
+ multicolored patterns, and means that the color you pass to the drawing
+ routine is ignored. This is the fastest of the patterned modes.
+
+
+ In DRAW_MODE_SOLID_PATTERN, each pixel in the pattern bitmap is compared
+ with the mask color, which is zero in 256-color modes or bright pink for
+ truecolor data (maximum red and blue, zero green). If the pattern pixel
+ is solid, a pixel of the color you passed to the drawing routine is
+ written to the destination bitmap, otherwise a zero is written. The
+ pattern is thus treated as a monochrome bitmask, which lets you use the
+ same pattern to draw different shapes in different colors, but prevents
+ the use of multicolored patterns.
+
+
+ DRAW_MODE_MASKED_PATTERN is almost the same as DRAW_MODE_SOLID_PATTERN,
+ but the masked pixels are skipped rather than being written as zeros, so
+ the background shows through the gaps.
+
+
+ In DRAW_MODE_TRANS, the global color_map table or truecolor blender
+ functions are used to overlay pixels on top of the existing image. This
+ must only be used after you have set up the color mapping table (for 256
+ color modes) or blender functions (for truecolor modes). Because it
+ involves reading as well as writing the bitmap memory, translucent
+ drawing is very slow if you draw directly to video RAM, so wherever
+ possible you should use a memory bitmap instead.
+
+
+
+ This is a shortcut for toggling xor drawing mode on and off. Calling
+ xor_mode(TRUE) is equivalent to drawing_mode(DRAW_MODE_XOR, NULL, 0, 0).
+ Calling xor_mode(FALSE) is equivalent to
+ drawing_mode(DRAW_MODE_SOLID, NULL, 0, 0).
+
+
+
+In paletted video modes, translucency and lighting are implemented with a
+64k lookup table, which contains the result of combining any two colors c1
+and c2. You must set up this table before you use any of the translucency
+or lighting routines. Depending on how you construct the table, a range of
+different effects are possible. For example, translucency can be implemented
+by using a color halfway between c1 and c2 as the result of the combination.
+Lighting is achieved by treating one of the colors as a light level (0-255)
+rather than a color, and setting up the table appropriately. A range of
+specialised effects are possible, for instance replacing any color with any
+other color and making individual source or destination colors completely
+solid or invisible. Color mapping tables can be precalculated with the
+colormap utility, or generated at runtime. Read chapter "Structures and types
+defined by Allegro" for an internal description of the COLOR_MAP structure.
+
+
+ Global pointer to the color mapping table. You must allocate your own
+ COLOR_MAP either statically or dynamically and set color_map to it
+ before using any translucent or lit drawing functions in a 256-color
+ video mode! Example:
+
+ color_map = malloc(sizeof(COLOR_MAP));
+ if (!color_map)
+ abort_on_error("Not enough memory for color map!");
+ Fills the specified color mapping table with lookup data for doing
+ translucency effects with the specified palette. When combining the
+ colors c1 and c2 with this table, the result will be a color somewhere
+ between the two. The r, g, and b parameters specify the solidity of each
+ color component, ranging from 0 (totally transparent) to 255 (totally
+ solid). For 50% solidity, pass 128.
+
+
+ This function treats source color #0 as a special case, leaving the
+ destination unchanged whenever a zero source pixel is encountered, so that
+ masked sprites will draw correctly. This function will take advantage of
+ the global rgb_map variable to speed up color conversions. If the callback
+ function is not NULL, it will be called 256 times during the calculation,
+ allowing you to display a progress indicator. Example:
+
+ COLOR_MAP trans_table;
+ ...
+ /* Build a color lookup table for translucent drawing. */
+ create_trans_table(&trans_table, pal, 128, 128, 128, NULL);
+ Fills the specified color mapping table with lookup data for doing
+ lighting effects with the specified palette. When combining the colors c1
+ and c2 with this table, c1 is treated as a light level from 0-255. At
+ light level 255 the table will output color c2 unchanged, at light level
+ 0 it will output the r, g, b value you specify to this function, and at
+ intermediate light levels it will output a color somewhere between the
+ two extremes. The r, g, and b values are in the range 0-63.
+
+
+ This function will take advantage of the global rgb_ap variable to speed
+ up color conversions. If the callback function is not NULL, it will be
+ called 256 times during the calculation, allowing you to display a
+ progress indicator. Example:
+
+ COLOR_MAP light_table;
+ ...
+ /* Build a color lookup table for lighting effects. */
+ create_light_table(&light_table, pal, 0, 0, 0, NULL);
+ Fills the specified color mapping table with lookup data for doing
+ customised effects with the specified palette, calling the blend function
+ to determine the results of each color combination.
+
+
+ Your blend routine will be passed a pointer to the palette and the two
+ indices of the colors which are to be combined, and should fill in the RGB
+ structure with the desired result in 0-63 format. Allegro will then search
+ the palette for the closest match to the RGB color that you requested, so
+ it doesn't matter if the palette has no exact match for this color.
+
+
+ If the callback function is not NULL, it will be called 256 times during
+ the calculation, allowing you to display a progress indicator. Example:
+
+ COLOR_MAP greyscale_table;
+ ...
+ void return_grey_color(const PALETTE pal,
+ int x, int y, RGB *rgb)
+ {
+ ...
+ }
+ ...
+ /* Build a color lookup table for greyscale effect. */
+ create_color_table(&greyscale_table, pal,
+ return_grey_color, NULL);
+ Fills the specified color mapping table with lookup data for doing a
+ paletted equivalent of whatever truecolor blender mode is currently
+ selected. After calling set_trans_blender(), set_blender_mode(), or any
+ of the other truecolor blender mode routines, you can use this function
+ to create an 8-bit mapping table that will have the same results as
+ whatever 24-bit blending mode you have enabled.
+
+
+
+In truecolor video modes, translucency and lighting are implemented by a
+blender function of the form:
+
+ unsigned long (*BLENDER_FUNC)(unsigned long x, y, n);
+
+
+For each pixel to be drawn, this routine is passed two color parameters x
+and y, decomposes them into their red, green and blue components, combines
+them according to some mathematical transformation involving the
+interpolation factor n, and then merges the result back into a single
+return color value, which will be used to draw the pixel onto
+the destination bitmap.
+
+
+The parameter x represents the blending modifier color and the parameter y
+represents the base color to be modified. The interpolation factor n is in
+the range [0-255] and controls the solidity of the blending.
+
+
+When a translucent drawing function is used, x is the color of the source,
+y is the color of the bitmap being drawn onto and n is the alpha level
+that was passed to the function that sets the blending mode (the RGB triplet
+that was passed to this function is not taken into account).
+
+
+When a lit sprite drawing function is used, x is the color represented by
+the RGB triplet that was passed to the function that sets the blending mode
+(the alpha level that was passed to this function is not taken into
+account), y is the color of the sprite and n is the alpha level that was
+passed to the drawing function itself.
+
+
+Since these routines may be used from various different color depths, there
+are three such callbacks, one for use with 15-bit 5.5.5 pixels, one for 16
+bit 5.6.5 pixels, and one for 24-bit 8.8.8 pixels (this can be shared
+between the 24 and 32-bit code since the bit packing is the same).
+
+
+ Enables the special alpha-channel blending mode, which is used for
+ drawing 32-bit RGBA sprites. After calling this function, you can use
+ draw_trans_sprite() or draw_trans_rle_sprite() to draw a 32-bit source
+ image onto any hicolor or truecolor destination. The alpha values will be
+ taken directly from the source graphic, so you can vary the solidity of
+ each part of the image. You can't use any of the normal translucency
+ functions while this mode is active, though, so you should reset to one
+ of the normal blender modes (eg. set_trans_blender()) before drawing
+ anything other than 32-bit RGBA sprites.
+
+
+
+ Enables the special alpha-channel editing mode, which is used for drawing
+ alpha channels over the top of an existing 32-bit RGB sprite, to turn it
+ into an RGBA format image. After calling this function, you can set the
+ drawing mode to DRAW_MODE_TRANS and then write draw color values (0-255)
+ onto a 32-bit image. This will leave the color values unchanged, but
+ alter the alpha to whatever values you are writing. After enabling this
+ mode you can also use draw_trans_sprite() to superimpose an 8-bit alpha
+ mask over the top of an existing 32-bit sprite.
+
+
+
+ Enables a burn blender mode for combining translucent or lit truecolor
+ pixels. Here the lightness values of the colours of the source image
+ reduce the lightness of the destination image, darkening the image.
+
+
+
+ Enables a color blender mode for combining translucent or lit truecolor
+ pixels. Applies only the hue and saturation of the source image to the
+ destination image. The luminance of the destination image is not affected.
+
+
+
+ Enables a difference blender mode for combining translucent or lit
+ truecolor pixels. This makes an image which has colours calculated by the
+ difference between the source and destination colours.
+
+
+
+ Enables a dissolve blender mode for combining translucent or lit
+ truecolor pixels. Randomly replaces the colours of some pixels in the
+ destination image with those of the source image. The number of pixels
+ replaced depends on the alpha value (higher value, more pixels replaced;
+ you get the idea :).
+
+
+
+ Enables a dodge blender mode for combining translucent or lit truecolor
+ pixels. The lightness of colours in the source lighten the colours of the
+ destination. White has the most effect; black has none.
+
+
+
+ Enables an invert blender mode for combining translucent or lit truecolor
+ pixels. Blends the inverse (or negative) colour of the source with the
+ destination.
+
+
+
+ Enables a luminance blender mode for combining translucent or lit
+ truecolor pixels. Applies the luminance of the source to the destination.
+ The colour of the destination is not affected.
+
+
+
+ Enables a multiply blender mode for combining translucent or lit
+ truecolor pixels. Combines the source and destination images, multiplying
+ the colours to produce a darker colour. If a colour is multiplied by
+ white it remains unchanged; when multiplied by black it also becomes
+ black.
+
+
+
+ Enables a saturation blender mode for combining translucent or lit
+ truecolor pixels. Applies the saturation of the source to the destination
+ image.
+
+
+
+ Enables a screen blender mode for combining translucent or lit truecolor
+ pixels. This blender mode lightens the colour of the destination image by
+ multiplying the inverse of the source and destination colours. Sort of
+ like the opposite of the multiply blender mode.
+
+
+
void set_blender_mode(BLENDER_FUNC b15, b16, b24, int r, g, b, a);
+ Specifies a custom set of truecolor blender routines, which can be used
+ to implement whatever special interpolation modes you need. This function
+ shares a single blender between the 24 and 32-bit modes.
+
+
+
+ Like set_blender_mode(), but allows you to specify a more complete set of
+ blender routines. The b15, b16, b24, and b32 routines are used when
+ drawing pixels onto destinations of the same format, while b15x, b16x,
+ and b24x are used by draw_trans_sprite() and draw_trans_rle_sprite() when
+ drawing RGBA images onto destination bitmaps of another format. These
+ blenders will be passed a 32-bit x parameter, along with a y value of a
+ different color depth, and must try to do something sensible in response.
+
+
+
+
+
bestfit_color — Finds a palette color fitting the requested RGB values.
+
create_rgb_table — Generates an RGB mapping table with lookup data for a palette.
+
hsv_to_rgb — Converts color values between the HSV and RGB colorspaces.
+
rgb_map — Look up table to speed up reducing RGB values to palette colors.
+
rgb_to_hsv — Converts color values between the HSV and RGB colorspaces.
+
+
+
+In general, Allegro is designed to be used in only one color depth at a
+time, so you will call set_color_depth() once and then store all your
+bitmaps in the same format. If you want to mix several different pixel
+formats, you can use create_bitmap_ex() in place of create_bitmap(), and
+call bitmap_color_depth() to query the format of a specific image. Most of
+the graphics routines require all their input parameters to be in the same
+format (eg. you cannot stretch a 15-bit source bitmap onto a 24-bit
+destination), but there are some exceptions:
+
+ blit() and the rotation routines can copy between bitmaps of any format,
+ converting the data as required.
+
+ draw_sprite() can draw 256-color source images onto destinations of any
+ format.
+
+ draw_character_ex() _always_ uses a 256-color source bitmap, whatever the
+ format of the destination.
+
+ The draw_trans_sprite() and draw_trans_rle_sprite() functions are able to
+ draw 32-bit RGBA images onto any hicolor or truecolor destination, as long
+ as you call set_alpha_blender() first.
+
+ The draw_trans_sprite() function is able to draw an 8-bit alpha channel
+ image over the top of an existing 32-bit image, as long as you call
+ set_write_alpha_blender() first.
+
+Expanding a 256-color source onto a truecolor destination is fairly fast
+(obviously you must set the correct palette before doing this conversion!).
+Converting between different truecolor formats is slightly slower, and
+reducing truecolor images to a 256-color destination is very slow (it can be
+sped up significantly if you set up the global rgb_map table before doing
+the conversion).
+
+
+ Searches the specified palette for the closest match to the requested
+ color, which are specified in the VGA hardware 0-63 format. Normally you
+ should call makecol8() instead, but this lower level function may be
+ useful if you need to use a palette other than the currently selected
+ one, or specifically don't want to use the rgb_map lookup table.
+
Return value:
+ Returns the index of the palette for the closest match to the requested
+ color.
+
+
+
+ To speed up reducing RGB values to 8-bit paletted colors, Allegro uses a
+ 32k lookup table (5 bits for each color component). You must set up this
+ table before using the gouraud shading routines, and if present the table
+ will also vastly accelerate the makecol8() and some create_*_table()
+ functions. RGB tables can be precalculated with the rgbmap utility, or
+ generated at runtime with create_rgb_table().
+
+
+
+ Fills the specified RGB mapping table with lookup data for the specified
+ palette. If the callback function is not NULL, it will be called 256
+ times during the calculation, allowing you to display a progress
+ indicator. Example:
+
void hsv_to_rgb(float h, float s, float v, int *r, int *g, int *b);
+
void rgb_to_hsv(int r, int g, int b, float *h, float *s, float *v);
+ Convert color values between the HSV and RGB colorspaces. The RGB values
+ range from 0 to 255, hue is from 0 to 360, and saturation and value are
+ from 0 to 1. Example:
+
+ int r, g, b;
+ float hue, saturation, value;
+ ...
+ /* Convert a reddish color to HSV format. */
+ rgb_to_hsv(255, 0, 128, &hue, &saturation, &value);
+
+ /* Now put our tin foil hat, and verify that. */
+ hsv_to_rgb(hue, saturation, value, &r, &g, &b);
+ ASSERT(r == 255);
+ ASSERT(g == 0);
+ ASSERT(b == 128);
bmp_write_line — Direct access bank switching line selection for writing.
+
+
+
+Read chapter "Structures and types defined by Allegro" for an internal
+description of the BITMAP structure. There are several ways to get direct
+access to the image memory of a bitmap, varying in complexity depending on
+what sort of bitmap you are using.
+
+
+The simplest approach will only work with memory bitmaps (obtained from
+create_bitmap(), grabber datafiles, and image files) and sub-bitmaps of
+memory bitmaps. This uses a table of char pointers, called `line', which is
+a part of the bitmap structure and contains pointers to the start of each
+line of the image. For example, a simple memory bitmap putpixel function is:
+
+ void memory_putpixel(BITMAP *bmp, int x, int y, int color)
+ {
+ bmp->line[y][x] = color;
+ }
+
+For truecolor modes you need to cast the line pointer to the appropriate
+type, for example:
+
+ void memory_putpixel_15_or_16_bpp(BITMAP *bmp, int x, int y, int color)
+ {
+ ((short *)bmp->line[y])[x] = color;
+ }
+
+ void memory_putpixel_32(BITMAP *bmp, int x, int y, int color)
+ {
+ ((long *)bmp->line[y])[x] = color;
+ }
+
+If you want to write to the screen as well as to memory bitmaps, you need to
+use some helper macros, because the video memory may not be part of your
+normal address space. This simple routine will work for any linear screen,
+eg. a VESA linear framebuffers:
+
+ void linear_screen_putpixel(BITMAP *bmp, int x, int y, int color)
+ {
+ bmp_select(bmp);
+ bmp_write8((unsigned long)bmp->line[y]+x, color);
+ }
+
+For truecolor modes you should replace the bmp_write8() with bmp_write16(),
+bmp_write24(), or bmp_write32(), and multiply the x offset by the number of
+bytes per pixel. There are of course similar functions to read a pixel value
+from a bitmap, namely bmp_read8(), bmp_read16(), bmp_read24() and
+bmp_read32().
+
+
+This still won't work in banked SVGA modes, however, or on platforms like
+Windows that do special processing inside the bank switching functions. For
+more flexible access to bitmap memory, you need to call the following
+routines. They are implemented as inline assembler routines, so they are not
+as inefficient as they might seem. If the bitmap doesn't require bank
+switching (ie. it is a memory bitmap, mode 13h screen, etc), these functions
+just return bmp->line[line].
+
+
+ Releases the bitmap memory after you are finished with it. You only need
+ to call this once at the end of a drawing operation, even if you have
+ called bmp_write_line() or bmp_read_line() several times before it.
+
+
+
+Although SVGA bitmaps are banked, Allegro provides linear access to the
+memory within each scanline, so you only need to pass a y coordinate to
+these functions. Various x positions can be obtained by simply adding the x
+coordinate to the returned address. The return value is an unsigned long
+rather than a char pointer because the bitmap memory may not be in your data
+segment, and you need to access it with far pointers. For example, a
+putpixel using the bank switching functions is:
+
+ void banked_putpixel(BITMAP *bmp, int x, int y, int color)
+ {
+ unsigned long address = bmp_write_line(bmp, y);
+ bmp_select(bmp);
+ bmp_write8(address+x, color);
+ bmp_unwrite_line(bmp);
+ }
+
+You will notice that Allegro provides separate functions for setting the
+read and write banks. It is important that you distinguish between these,
+because on some graphics cards the banks can be set individually, and on
+others the video memory is read and written at different addresses. Life is
+never quite as simple as we might wish it to be, though (this is true even
+when we _aren't_ talking about graphics coding :-) and so of course some
+cards only provide a single bank. On these the read and write bank functions
+will behave identically, so you shouldn't assume that you can read from one
+part of video memory and write to another at the same time. You can call
+bmp_read_line(), and read whatever you like from that line, and then call
+bmp_write_line() with the same or a different line number, and write
+whatever you like to this second line, but you mustn't call bmp_read_line()
+and bmp_write_line() together and expect to be able to read one line and
+write the other simultaneously. It would be nice if this was possible, but
+if you do it, your code won't work on single banked SVGA cards.
+
+
+And then there's mode-X. If you've never done any mode-X graphics coding,
+you probably won't understand this, but for those of you who want to know
+how Allegro sets up the mode-X screen bitmaps, here goes...
+
+
+The line pointers are still present, and they contain planar addresses, ie.
+the actual location at which you access the first pixel in the line. These
+addresses are guaranteed to be quad aligned, so you can just set the write
+plane, divide your x coordinate by four, and add it to the line pointer. For
+example, a mode-X putpixel is:
+
+ void modex_putpixel(BITMAP *b, int x, int y, int color)
+ {
+ outportw(0x3C4, (0x100<<(x&3))|2);
+ bmp_select(bmp);
+ bmp_write8((unsigned long)bmp->line[y]+(x>>2), color);
+ }
+
+
+Oh yeah: the DJGPP nearptr hack. Personally I don't like this very much
+because it disables memory protection and isn't portable to other platforms,
+but a lot of people swear by it because it can give you direct access to the
+screen memory via a normal C pointer. Warning: this method will only work
+with the DJGPP library, when using VGA 13h or a linear framebuffer modes!
+
+
fli_bmp_dirty_to — Indicate which parts of the image have changed.
+
fli_frame — Stores the current frame number of the animation.
+
fli_pal_dirty_from — Indicate which parts of the palette have changed.
+
fli_pal_dirty_to — Indicate which parts of the palette have changed.
+
fli_palette — Contains the current palette of the animation.
+
fli_timer — Global variable for timing FLI playback.
+
next_fli_frame — Reads the next frame of the current animation file.
+
open_fli — Makes a FLI file open and ready for playing.
+
open_memory_fli — Makes a FLI file open and ready for playing.
+
play_fli — Plays a FLI or FLC animation from disk.
+
play_memory_fli — Plays a FLI or FLC animation from memory.
+
reset_fli_variables — Resets the bitmap and palette dirty global variables.
+
+
+
+There are two high level functions for playing FLI/FLC animations:
+play_fli(), which reads the data directly from disk, and play_memory_fli(),
+which uses data that has already been loaded into RAM. Apart from the
+different sources of the data, these two functions behave identically. They
+draw the animation onto the specified bitmap, which should normally be the
+screen. Frames will be aligned with the top left corner of the bitmap: if
+you want to position them somewhere else you will need to create a
+sub-bitmap for the FLI player to draw onto.
+
+
+If the callback function is not NULL it will be called once for each frame,
+allowing you to perform background tasks of your own. This callback should
+normally return zero: if it returns non-zero the player will terminate (this
+is the only way to stop an animation that is playing in looped mode).
+
+
+The FLI player returns FLI_OK if it reached the end of the file, FLI_ERROR
+if something went wrong, and the value returned by the callback function if
+that was what stopped it. If you need to distinguish between different return
+values, your callback should return positive integers, since FLI_OK is zero
+and FLI_ERROR is negative.
+
+
+Note that the FLI player will only work when the timer module is installed,
+and that it will alter the palette according to whatever palette data is
+present in the animation file.
+
+
+Occasionally you may need more detailed control over how an FLI is played,
+for example if you want to superimpose a text scroller on top of the
+animation, or to play it back at a different speed. You could do both of
+these with the lower level functions described below.
+
+
+
int play_fli(const char *filename, BITMAP *bmp, int loop, int (*callback)());
+ Plays an Autodesk Animator FLI or FLC animation file on the specified
+ BITMAP, reading the data from disk as it is required. If `loop' is not
+ zero, the player will cycle when it reaches the end of the file, otherwise
+ it will play through the animation once and then return. Read the beginning
+ of chapter "FLIC routines" for a description of the callback parameter.
+ Example:
+
+ /* Let users skip looped animations. */
+ int check_escape_key(void)
+ {
+ if (key[KEY_ESC])
+ return 1;
+ else
+ return 0;
+ }
+ ...
+ int ret = play_fli("animlogo.fli", screen, 1,
+ check_escape_key);
+ if (ret == FLI_ERROR)
+ abort_on_error("Error playing intro!");
+
Return value:
+ The FLI player returns FLI_OK if it reached the end of the file, FLI_ERROR
+ if something went wrong, and the value returned by the callback function if
+ that was what stopped it.
+
+
+
int play_memory_fli(const void *fli_data, BITMAP *bmp, int loop,
+ int (*callback)());
+ Plays an Autodesk Animator FLI or FLC animation on the specified BITMAP,
+ reading the data from a copy of the file which is held in memory. You can
+ obtain the `fli_data' pointer by mallocing a block of memory and reading
+ an FLI file into it, or by importing an FLI into a grabber datafile. If
+ `loop' is not zero, the player will cycle when it reaches the end of the
+ file, otherwise it will play through the animation once and then return.
+ Read the beginning of chapter "FLIC routines" for a description of the
+ callback parameter.
+
+
+ Playing animations from memory is obviously faster than cueing them
+ directly from disk, and is particularly useful with short, looped FLI's.
+ Animations can easily get very large, though, so in most cases you will
+ probably be better just using play_fli(). You can think of this function
+ as a wrapper on top of open_memory_fli(), next_fli_frame() and close_fli().
+ Example:
+
+ int ret = play_memory_fli(anim_data, screen, 0, NULL);
+ if (ret == FLI_ERROR)
+ abort_on_error("Corrupted animation data?");
+
Return value:
+ The FLI player returns FLI_OK if it reached the end of the file, FLI_ERROR
+ if something went wrong, and the value returned by the callback function if
+ that was what stopped it.
+
+
+
+ Open FLI files ready for playing, reading the data from disk or memory
+ respectively. Information about the current FLI is held in the global
+ variables fli_bitmap and fli_palette, which you can use if this function
+ succeeds. However, you can only have one animation open at a time.
+ Example:
+
+ if (open_fli("intro.fli") == FLI_ERROR)
+ abort_on_error("Error playing intro");
+
Return value:
+ Returns FLI_OK on success, FLI_ERROR if something went wrong, like trying
+ to open another FLI file without closing the previous one.
+
+
+
+ Reads the next frame of the current animation file. If `loop' is not zero,
+ the player will cycle when it reaches the end of the file, otherwise it
+ will return FLI_EOF. The frame is read into the global variables
+ fli_bitmap and fli_palette. Example:
+
+ while (next_fli_frame(0) == FLI_OK) {
+ /* Do stuff, like play audio stream
+ or check keys to skip animation. */
+ /* Rest some time until next frame... */
+ }
+
Return value:
+ Returns FLI_OK on success, FLI_ERROR or FLI_NOT_OPEN on error, and FLI_EOF
+ on reaching the end of the file.
+
+
+
+ These variables are set by next_fli_frame() to indicate which part of the
+ fli_bitmap has changed since the last call to reset_fli_variables(). If
+ fli_bmp_dirty_from is greater than fli_bmp_dirty_to, the bitmap has not
+ changed, otherwise lines fli_bmp_dirty_from to fli_bmp_dirty_to
+ (inclusive) have altered. You can use these when copying the fli_bitmap
+ onto the screen, to avoid moving data unnecessarily. Example:
+
+ These variables are set by next_fli_frame() to indicate which part of the
+ fli_palette has changed since the last call to reset_fli_variables(). If
+ fli_pal_dirty_from is greater than fli_pal_dirty_to, the palette has not
+ changed, otherwise colors fli_pal_dirty_from to fli_pal_dirty_to
+ (inclusive) have altered. You can use these when updating the hardware
+ palette, to avoid unnecessary calls to set_palette(). Example:
+
+ Once you have done whatever you are going to do with the fli_bitmap and
+ fli_palette, call this function to reset the fli_bmp_dirty_* and
+ fli_pal_dirty_* variables.
+
+
+
+ Global variable containing the current frame number in the FLI file. This
+ is useful for synchronising other events with the animation, for instance
+ you could check it in a play_fli() callback function and use it to
+ trigger a sample at a particular point. Example:
+
+ while (next_fli_frame(0) == FLI_OK) {
+ if (fli_frame == 345)
+ play_sample(trumpet_sound, 255, 128, 1000, 0);
+ /* Rest some time until next frame... */
+ }
+ Global variable for timing FLI playback. When you open an FLI file, a
+ timer interrupt is installed which increments this variable every time a
+ new frame should be displayed. Calling next_fli_frame() decrements it, so
+ you can test it and know that it is time to display a new frame if it is
+ greater than zero. Example:
+
+ while (next_fli_frame(0) == FLI_OK) {
+ /* Do stuff, like play audio stream
+ or check keys to skip animation. */
+ /* Rest some time until next frame... */
+ while (fli_timer <= 0)
+ rest(0);
+ }
+Allegro allows you to use the sound hardware in two ways: automatic, or
+manual. Usually you should try the automatic version first. This means
+calling install_sound() with the autodetection parameters and using the rest
+of the sound functions to play samples or music. In this situation, Allegro
+will handle the sound devices and mix the samples and/or music the best way
+it can.
+
+
+However, sound hardware has a limitation on the number of samples it may
+play all at the same time (from now on, called hardware voices). When you
+exceed this limit, Allegro will cut off one of the samples being played and
+reproduce the new one. Depending on the type of sounds you are playing, how
+many of them you need at the same time and their nature (e.g: vital audio
+feedback to the user or useless "ping" when some shrapnel hits a rock in the
+scenary) you will want to specify more carefully how hardware voices are
+reserved and which samples have priority over others.
+
+
+The hardware voice reservation phase has to be done before the call to
+install_sound(), since it directly affects how Allegro talks to the sound
+drivers.
+
+
+ Detects whether the specified MIDI sound device is available. This function
+ must be called _before_ install_sound().
+
Return value:
+ Returns the maximum number of voices that the driver can provide, or zero
+ if the hardware is not present.
+
+
+ There are two special-case return values that you should watch out for:
+ if this function returns -1 it is a note-stealing driver (eg. DIGMID) that
+ shares voices with the current digital sound driver, and if it returns
+ 0xFFFF it is an external device like an MPU-401 where there is no way to
+ determine how many voices are available.
+
+
+
+ Call this function to specify the number of voices that are to be used by
+ the digital and MIDI sound drivers respectively. This must be done
+ _before_ calling install_sound(). If you reserve too many voices,
+ subsequent calls to install_sound() will fail. How many voices are
+ available depends on the driver, and in some cases you will actually get
+ more than you reserve (eg. the FM synth drivers will always provide 9
+ voices on an OPL2 and 18 on an OPL3, and the SB digital driver will round
+ the number of voices up to the nearest power of two). Pass negative
+ values to restore the default settings. You should be aware that the
+ sound quality is usually inversely related to how many voices you use, so
+ don't reserve any more than you really need.
+
+
+
+ By default, Allegro will play a centered sample at half volume on both
+ the left and right channel. A sample panned to the far right or left
+ will be played at maximum volume on that channel only. This is done so
+ you can play a single panned sample without distortion. If you play
+ multiple samples at full volume, the mixing process can result in
+ clipping, a noticeable form of distortion. The more samples, the more
+ likely clipping is to occur, and the more clipping, the worse the output
+ will sound.
+
+
+ If clipping is a problem - or if the output is too quiet - this function
+ can be used to adjust the volume of each voice. You should first check
+ that your speakers are at a reasonable volume, Allegro's global volume
+ is at maximum (see set_volume() below), and any other mixers such as the
+ Windows Volume Control are set reasonably. Once you are sure that
+ Allegro's output level is unsuitable for your application, use this
+ function to adjust it.
+
+
+ Each time you increase the parameter by one, the volume of each voice
+ will halve. For example, if you pass 4, you can play up to 16 centred
+ samples at maximum volume without distortion.
+
+
+ If you pass 0 to this function, each centred sample will play at the
+ maximum volume possible without distortion, as will all samples played
+ through a mono driver. Samples at the extreme left and right will distort
+ if played at full volume. If you wish to play panned samples at full
+ volume without distortion, you should pass 1 to this function.
+ Note: this is different from the function's behaviour in WIPs 3.9.34,
+ 3.9.35 and 3.9.36. If you used this function under one of these WIPs,
+ you will have to increase your parameter by one to get the same volume.
+
+
+ Note: The default behaviour has changed as of Allegro 4.1.15. If you
+ would like the behaviour of earlier versions of Allegro, pass -1 to this
+ function. Allegro will choose a value dependent on the number of voices,
+ so that if you reserve n voices, you can play up to n/2 normalised
+ samples with centre panning without risking distortion. The exception is
+ when you have fewer than 8 voices, where the volume remains the same as
+ for 8 voices. Here are the values, dependent on the number of voices:
+
+ Of course this function does not override the volume you specify with
+ play_sample() or voice_set_volume(). It simply alters the overall output
+ of the program. If you play samples at lower volumes, or if they are not
+ normalised, then you can play more of them without distortion.
+
+
+ It is recommended that you hard-code the parameter into your program,
+ rather than offering it to the user. The user can alter the volume with
+ the configuration file instead, or you can provide for this with
+ set_volume().
+
+
+ To restore volume per voice to its default behaviour, pass 1.
+
+
+
int install_sound(int digi, int midi, const char *cfg_path);
+ Initialises the sound module. You should normally pass DIGI_AUTODETECT
+ and MIDI_AUTODETECT as the driver parameters to this function, in which
+ case Allegro will read hardware settings from the current configuration
+ file. This allows the user to select different values with the setup
+ utility: see the config section for details. Alternatively, see the
+ platform specific documentation for a list of the available drivers. The
+ cfg_path parameter is only present for compatibility with previous
+ versions of Allegro, and has no effect on anything.
+
Return value:
+ Returns zero if the sound is successfully installed, and -1 on failure.
+ If it fails it will store a description of the problem in allegro_error.
+
+
+
void set_volume(int digi_volume, int midi_volume);
+ Alters the global sound output volume. Specify volumes for both digital
+ samples and MIDI playback, as integers from 0 to 255, or pass a negative
+ value to leave one of the settings unchanged. Values bigger than 255 will
+ be reduced to 255. This routine will not alter the volume of the hardware
+ mixer if it exists (i.e. only your application will be affected).
+
+
+
+ Alters the hardware sound output volume. Specify volumes for both digital
+ samples and MIDI playback, as integers from 0 to 255, or pass a negative
+ value to leave one of the settings unchanged. Values bigger than 255 will
+ be reduced to 255. This routine will use the hardware mixer to control the
+ volume if it exists (i.e. the volume of all the applications on your
+ machine will be affected), otherwise do nothing.
+
+
+
void get_volume(int *digi_volume, int *midi_volume);
+ Retrieves the global sound output volume, both for digital samples and MIDI
+ playback, as integers from 0 to 255. Parameters digi_volume and midi_volume
+ must be valid pointers to int, or NULL if not interested in specific value.
+
+
+
+ Retrieves the hardware sound output volume, both for digital samples and MIDI
+ playback, as integers from 0 to 255, or -1 if the information is not
+ available. Parameters digi_volume and midi_volume must be valid pointers to
+ int, or NULL if not interested in specific value.
+
+
+
+ Sets the resampling quality of the mixer. Valid values are the same as
+ the `quality' config variable. Please read chapter "Standard config
+ variables" for details. You can call this function at any point in your
+ program, even before allegro_init().
+
+
+
+ Loads a sample from a file, supporting both mono and stereo WAV and mono
+ VOC files, in 8 or 16-bit formats, as well as formats handled by functions
+ registered using register_sample_file_type(). Example:
+
+ Writes a sample into a file. The output format is determined from the
+ filename extension. At present Allegro does not natively support the
+ writing of any sample formats, so you must register a custom saver routine
+ with register_sample_file_type(). Example:
+
+ if (save_sample("sound.wav", sample) != 0)
+ abort_on_error("Couldn't save sample!");
+
Return value:
+ Returns zero on success, non-zero otherwise.
+
+
+
+ Constructs a new sample structure of the specified type. Read chapter
+ "Structures and types defined by Allegro" for an internal description of
+ the SAMPLE structure. The `bits' parameter can be 8 or 16, `stereo' can be
+ zero for mono samples and non-zero for stereo samples, `freq' is the
+ frequency in hertz, and `len' is the number of samples you want to allocate
+ for the full sound buffer.
+
Return value:
+ Returns a pointer to the created sample, or NULL if the sample could not
+ be created. Remember to free this sample later to avoid memory leaks.
+
+
+
+ Destroys a sample structure when you are done with it. It is safe to call
+ this even when the sample might be playing, because it checks and will
+ kill it off if it is active. Use this to avoid memory leaks in your
+ program.
+
+
+
+ Under DOS, locks all the memory used by a sample. You don't normally need
+ to call this function because load_sample() and create_sample() do it for
+ you.
+
+
+
+ Informs the load_sample() function of a new sample file type,
+ providing routines to read and write samples in this format (either
+ function may be NULL). Example:
+
int play_sample(const SAMPLE *spl, int vol, int pan, int freq, int loop);
+ Triggers a sample at the specified volume, pan position, and frequency.
+ The parameters `vol' and `pan' range from 0 (min/left) to 255 (max/right).
+ Frequency is relative rather than absolute: 1000 represents the frequency
+ that the sample was recorded at, 2000 is twice this, etc. If `loop' is not
+ zero, the sample will repeat until you call stop_sample(), and can be
+ manipulated while it is playing by calling adjust_sample(). Example:
+
+ /* Scream from the left speaker, twice the freq. */
+ int sound = play_sample(scream, 255, 0, 2000, 0);
+
Return value:
+ Returns the voice number that was allocated for the sample or negative if
+ no voices were available.
+
+
+
void adjust_sample(const SAMPLE *spl, int vol, int pan, int freq, int loop);
+ Alters the parameters of a sample while it is playing (useful for
+ manipulating looped sounds). You can alter the volume, pan, and frequency,
+ and can also clear the loop flag, which will stop the sample when it next
+ reaches the end of its loop. The values of the parameters are just like
+ those of play_sample(). If there are several copies of the same sample
+ playing, this will adjust the first one it comes across. If the sample is
+ not playing it has no effect.
+
+
+
+ Kills off a sample, which is required if you have set a sample going in
+ looped mode. If there are several copies of the sample playing, it will
+ stop them all.
+
+
+
+If you need more detailed control over how samples are played, you can use
+the lower level voice functions rather than just calling play_sample(). This
+is rather more work, because you have to explicitly allocate and free the
+voices rather than them being automatically released when they finish
+playing, but allows far more precise specification of exactly how you want
+everything to sound. You may also want to modify a couple of fields from the
+SAMPLE structure. Read chapter "Structures and types defined by Allegro" for
+its definition.
+
+
+
+ Allocates a soundcard voice and prepares it for playing the specified
+ sample, setting up sensible default parameters (maximum volume, centre
+ pan, no change of pitch, no looping). When you are finished with the
+ voice you must free it by calling deallocate_voice() or release_voice().
+ Allegro can manage up to 256 simultaneous voices, but that limit may be
+ lower due to hardware reasons.
+
Return value:
+ Returns the voice number, or -1 if no voices are available.
+
+
+
+ Releases a soundcard voice, indicating that you are no longer interested
+ in manipulating it. The sound will continue to play, and any resources
+ that it is using will automatically be freed when it finishes. This is
+ essentially the same as deallocate_voice(), but it waits for the sound to
+ stop playing before taking effect.
+
+
+
+ Sets the priority of a voice (range 0-255). This is used to decide which
+ voices should be chopped off, if you attempt to play more than the
+ soundcard driver can handle.
+
+
+
+ Checks whether a voice is currently allocated.
+
Return value:
+ Returns a pointer to the sample that the voice is using, or NULL if the
+ voice is inactive (ie. it has been deallocated, or the release_voice()
+ function has been called and the sample has then finished playing).
+
+
+
+ Adjusts the loop status of the specified voice. This can be done while
+ the voice is playing, so you can start a sample in looped mode (having
+ set the loop start and end positions to the appropriate values), and then
+ clear the loop flag when you want to end the sound, which will cause it
+ to continue past the loop end, play the subsequent part of the sample,
+ and finish in the normal way. The mode parameter is a bitfield containing
+ the following values:
+
+ PLAYMODE_PLAY
+ Plays the sample a single time. This is the default if you don't set
+ the loop flag.
+
+ PLAYMODE_LOOP
+ Loops repeatedly through the sample, jumping back to the loop start
+ position upon reaching the loop end.
+
+ PLAYMODE_FORWARD
+ Plays the sample from beginning to end. This is the default if you
+ don't set the backward flag.
+
+ PLAYMODE_BACKWARD
+ Reverses the direction of the sample. If you combine this with the
+ loop flag, the sample jumps to the loop end position upon reaching the
+ loop start (ie. you do not need to reverse the loop start and end
+ values when you play the sample in reverse).
+
+ PLAYMODE_BIDIR
+ When used in combination with the loop flag, causes the sample to
+ change direction each time it reaches one of the loop points, so it
+ alternates between playing forwards and in reverse.
+
+ Returns the current volume of the voice, range 0-255. Otherwise it
+ returns -1 if that cannot be determined (because it has finished or
+ been preempted by a different sound).
+
+
+
+ Starts a volume ramp (crescendo or diminuendo) from the current volume to
+ the specified ending volume, lasting for time milliseconds. The volume is
+ a value in the range 0-255.
+
+
+
midi_pos — Stores the current position in the MIDI file.
+
midi_resume — Resumes playback of a paused MIDI file.
+
midi_seek — Seeks to the given midi_pos in the current MIDI file.
+
midi_sysex_callback — Hook functions allowing you to intercept MIDI player events.
+
midi_time — The current position in the MIDI file, in seconds.
+
play_looped_midi — Starts playing a MIDI file with a user-defined loop position.
+
play_midi — Starts playing the specified MIDI file.
+
stop_midi — Stops whatever music is currently playing.
+
+
+
+Allegro allows you to play MIDI files. MIDI files basically contain notes and
+the type of instrument that is meant to play them, so they are usually very
+small in size. However, it's up to the soundcard of the end user to play the
+notes, and soundcards have been historically known to have poor MIDI
+performance (at least those oriented to the consumer market). Few consumer
+cards feature decent MIDI playback. Still, as a game creator you can never be
+sure if the music of your game will be played as you meant it, because it
+totally depends on the hardware of the user.
+
+
+For this reason Allegro also provides a DIGMID driver. This is a software
+implementation of the so called Wavetable synthesis. Soundcards featuring this
+store digital samples of real instruments at different pitches, interpolating
+those that are not recorded, thus achieving a high sound quality. Implementing
+this in software makes you sure that the quality you hear on your computer is
+that which will be heard by end users using the same driver.
+
+
+The disadvantage of the DIGMID driver is that it uses more CPU than simple
+MIDI playback, and it steals some hardware voices from the soundcard, which
+might be more critical for the end user experience than the background music.
+At the Allegro homepage (http://alleg.sourceforge.net/) you can find more
+information about DIGMID and where to download digital samples for your MIDI
+files.
+
+
+ Destroys a MIDI structure when you are done with it. It is safe to call
+ this even when the MIDI file might be playing, because it checks and will
+ kill it off if it is active. Use this to avoid memory leaks in your
+ program.
+
+
+
+ Starts playing the specified MIDI file, first stopping whatever music was
+ previously playing. If the loop flag is set to non-zero, the data will be
+ repeated until replaced with something else, otherwise it will stop at the
+ end of the file. Passing a NULL pointer will stop whatever music is
+ currently playing.
+
Return value:
+ Returns non-zero if an error occurs (this may happen if a patch-caching
+ wavetable driver is unable to load the required samples, or at least it
+ might in the future when somebody writes some patch-caching wavetable
+ drivers :-)
+
+
+
+ Starts playing a MIDI file with a user-defined loop position. When the
+ player reaches the loop end position or the end of the file (loop_end may
+ be -1 to only loop at EOF), it will wind back to the loop start point.
+ Both positions are specified in the same beat number format as the
+ midi_pos variable.
+
Return value:
+ The return value has the same meaning as that of play_midi(): non-zero if
+ an error occurs, zero otherwise.
+
+
+
+ Seeks to the given midi_pos in the current MIDI file. If the target is
+ earlier in the file than the current midi_pos it seeks from the
+ beginning; otherwise it seeks from the current position.
+
Return value:
+ Returns zero if it could successfully seek to the requested position.
+ Otherwise, a return value of 1 means it stopped playing, and midi_pos is
+ set to the negative length of the MIDI file (so you can use this function
+ to determine the length of a MIDI file). A return value of 2 means the
+ MIDI file looped back to the start.
+
+
+
+ This function will simulate playing the given MIDI, from start to end, to
+ determine how long it takes to play. After calling this function, midi_pos
+ will contain the negative number of beats, and midi_time the length of the
+ midi, in seconds.
+
+
+ Note that any currently playing midi is stopped when you call this function.
+ Usually you would call it before play_midi, to get the length of the midi to
+ be played, like in this example:
+
+ Streams a block of MIDI commands into the player in realtime, allowing
+ you to trigger notes, jingles, etc, over the top of whatever MIDI file is
+ currently playing.
+
+
+
+ Forces the MIDI driver to load the entire set of patches ready for use.
+ You will not normally need to call this, because Allegro automatically
+ loads whatever data is required for the current MIDI file, but you must
+ call it before sending any program change messages via the midi_out()
+ command.
+
Return value:
+ Returns non-zero if an error occurred.
+
+
+
+ Stores the current position (beat number) in the MIDI file, or contains
+ a negative number if no music is currently playing. Useful for
+ synchronising animations with the music, and for checking whether a MIDI
+ file has finished playing.
+
+
+
+ Contains the position in seconds in the currently playing midi. This is
+ useful if you want to display the current song position in seconds, not as
+ beat number.
+
+
+
+ The loop start and end points, set by the play_looped_midi() function.
+ These may safely be altered while the music is playing, but you should be
+ sure they are always set to sensible values (start < end). If you are
+ changing them both at the same time, make sure to alter them in the right
+ order in case a MIDI interrupt happens to occur in between your two
+ writes! Setting these values to -1 represents the start and end of the
+ file respectively.
+
+
+
+ Hook functions allowing you to intercept MIDI player events. If set to
+ anything other than NULL, these routines will be called for each MIDI
+ message, meta-event, and system exclusive data block respectively. They
+ will execute in an interrupt handler context, so all the code and data
+ they use should be locked, and they must not call any operating system
+ functions. In general you just use these routines to set some flags and
+ respond to them later in your mainline code.
+
+
+
+ Reads in a .IBK patch definition file for use by the Adlib driver. If
+ drums is set, it will load it as a percussion patch set, otherwise it
+ will use it as a replacement set of General MIDI instruments. You may
+ call this before or after initialising the sound code, or can simply set
+ the ibk_file and ibk_drum_file variables in the configuration file to
+ have the data loaded automatically. Note that this function has no effect
+ on any drivers other than the Adlib one!
+
play_audio_stream — Creates a new audio stream and starts playing it.
+
stop_audio_stream — Destroys an audio stream when it is no longer required.
+
+
+
+The audio stream functions are for playing digital sounds that are too big
+to fit in a regular SAMPLE structure, either because they are huge files
+that you want to load in pieces as the data is required, or because you are
+doing something clever like generating the waveform on the fly.
+
+
+You can think of an AUDIOSTREAM structure as a wrapper around two audio
+buffers. The first thing you do is fill both buffers with sound data and let
+Allegro play them. Once the first buffer has been played, the second starts,
+and Allegro lets you know you have to fill the other one (i.e. graphics
+double buffering applied to sounds too big to fit into memory).
+
+
+The implementation of the sound buffers uses normal SAMPLE structures, so you
+can use all the voice_*() functions to modify the audio streams. Read chapter
+"Digital sample routines", section "Voice control" for a list of additional
+functions you can use. Read chapter "Structures and types defined by Allegro"
+for the internals of the AUDIOSTREAM structure.
+
+
+ This function creates a new audio stream and starts playing it. The
+ length is the size of each transfer buffer in sample frames (not bytes),
+ where a sample frame is a single sample value for mono data or a pair of
+ interleaved sample values (left first) for stereo data. The length should
+ normally be (but doesn't have to be) a power of 2 somewhere around 1k in
+ size. Larger buffers are more efficient and require fewer updates, but
+ result in more latency between you providing the data and it actually
+ being played.
+
+
+ The `bits' parameter must be 8 or 16. `freq' is the sample rate of the
+ data in Hertz. The `vol' and `pan' values use the same 0-255 ranges as the
+ regular sample playing functions. The `stereo' parameter should be set to
+ 1 for stereo streams, or 0 otherwise.
+
+
+ If you want to adjust the pitch, volume, or panning of a stream once it is
+ playing, you can use the regular voice_*() functions with stream->voice
+ as a parameter. The format of the sample data is described in the SAMPLE
+ entry of the "Structures and types defined by Allegro" chapter. The formula
+ to get the size of the buffers in bytes could be:
+
+ You must call this function at regular intervals while an audio stream is
+ playing, to provide the next buffer of sample data (the smaller the
+ stream buffer size, the more often it must be called). This function should
+ not be called from a timer handler. Example:
+
Return value:
+ If it returns NULL, the stream is still playing the previous lot of data,
+ so you don't need to do anything. If it returns a value, that is the
+ location of the next buffer to be played, and you should load the
+ appropriate number of samples (however many you specified when creating the
+ stream) to that address, for example using an fread() from a disk file.
+ After filling the buffer with data, call free_audio_stream_buffer() to
+ indicate that the new data is now valid.
+
+
+
+ Call this function after get_audio_stream_buffer() returns a non-NULL
+ address, to indicate that you have loaded a new block of samples to that
+ location and the data is now ready to be played. Example:
+
+Allegro provides routines to capture sound from the soundcard, be it digital
+samples or MIDI notes. Ideally this would allow you to create games where
+basic speech recognition could be implemented, or voice messages in
+multiplayer games over a network. However, many old sound cards are not full
+duplex. This means, that the sound device can only be playing or recording,
+but not both at the same time.
+
+
+Any Windows 2000 or better machine comes with a full duplex soundcard and
+updated drivers. All MacOS X machines allow full duplex recording. Under Unix
+your mileage may vary: you can have the right hardware for the task, but the
+drivers might not support this feature. Under DOS you should forget about full
+duplex altogether.
+
+
+To find out if your system allows this feature, use the akaitest program,
+distributed along with Allegro, in the `tests' directory.
+
+
+ Initialises the sound recorder module. You must install the normal sound
+ playback system before calling this routine. The two card parameters should
+ use the same constants as install_sound(), including DIGI_NONE and
+ MIDI_NONE to disable parts of the module, or DIGI_AUTODETECT and
+ MIDI_AUTODETECT to guess the hardware.
+
Return value:
+ This function returns zero on success, and any other value if the machine
+ or driver doesn't support sound recording.
+
+
+
+ Cleans up after you are finished with the sound input routines. You don't
+ normally need to call this, because remove_sound() and/or allegro_exit()
+ will do it for you.
+
+
+
+ Checks which sample formats are supported by the current audio input
+ driver, returning one of the bitfield values:
+
+ 0 = audio input not supported
+ 8 = eight bit audio input is supported
+ 16 = sixteen bit audio input is supported
+ 24 = both eight and sixteen bit audio input are supported
+ Example:
+
+ cap = get_sound_input_cap_bits();
+ if (cap == 0) {
+ /* Ugh, no audio input supported? */
+ } else {
+ if (cap & 8) {
+ /* We have eight bit audio input. */
+ }
+ if (cap & 16) {
+ /* We have sixteen bit audio input. */
+ }
+ }
+ Returns the maximum possible sample frequency for recording in the
+ specified format, or zero if these settings are not supported. The bits
+ parameter is the number of bits of the audio, and stereo is a boolean
+ parameter. Pass zero for mono, non-zero for stereo input. Example:
+
+ int max_freq;
+ ...
+ /* What frequency can we record 8 bits mono at? */
+ max_freq = get_sound_input_cap_rate(8, 0);
+ if (max_freq > 22000) {
+ /* Ok, 22KHz and above is good enough. */
+ }
+ Checks whether the specified recording frequency, number of bits, and
+ mono/stereo mode are supported (and how) by the current audio driver.
+
Return value:
+ The function returns one of the following possible values:
+
+ 0 = It is impossible to record in this format.
+ 1 = Recording is possible, but audio output
+ will be suspended.
+ 2 = Recording is possible at the same time as
+ playing other sounds (full duplex soundcard).
+ -n = Sampling rate not supported, but rate 'n'
+ would work instead.
Return value:
+ The function returns zero on success, or -1 if the hardware does not
+ provide an input select register (ie. you have no control over the input
+ source).
+
+
+
+ Retrieves the most recently recorded audio buffer into the specified
+ location. The buffer size can be obtained by checking the return value
+ from start_sound_input(). You must be sure to call this
+ function at regular intervals during the recording (typically around 100
+ times a second), or some data will be lost. If you are unable to do this
+ often enough from the mainline code, use the digi_recorder() callback to
+ store the waveform into a larger buffer of your own.
+
+
+ Note: many cards produce a click or popping sound when switching between
+ record and playback modes, so it is often a good idea to discard the
+ first buffer after you start a recording. The waveform is always stored
+ in unsigned format, with stereo data consisting of alternate left/right
+ samples.
+
Return value:
+ The function will return non-zero if a buffer has been copied or zero if
+ no new data is yet available (you were too fast checking the input).
+
+
+
+ If set, this function is called by the input driver whenever a new sample
+ buffer becomes available, at which point you can use read_sound_input()
+ to copy the data into a more permanent location. It runs in an interrupt
+ context, so it must execute very quickly, the code and all memory that it
+ touches must be locked, and you cannot call any operating system routines
+ or access disk files. This currently works only under DOS.
+
+
+
+ If set, this function is called by the MIDI input driver whenever a new
+ byte of MIDI data becomes available. It runs in an interrupt context, so
+ it must execute very quickly and all the code/data must be locked. This
+ currently works only under DOS and Windows.
+
+
+
+
+
+The following routines implement a fast buffered file I/O system, which
+supports the reading and writing of compressed files using a ring buffer
+algorithm based on the LZSS compressor by Haruhiko Okumura. This does not
+achieve quite such good compression as programs like zip and lha, but
+unpacking is very fast and it does not require much memory. Packed files
+always begin with the 32-bit value F_PACK_MAGIC, and autodetect files with
+the value F_NOPACK_MAGIC.
+
+
+The following FA_* flags are guaranteed to work:
+
+ FA_NONE - Exclude files that have any attribute set
+ FA_RDONLY - Directory entries that are unwritable for current user
+ FA_HIDDEN - Hidden flag
+ FA_DIREC - Directories
+ FA_SYSTEM - Files with system flag set (DOS/Windows only)
+ FA_LABEL - Files with volume label flag set (DOS/Windows only)
+ FA_ARCH - Files with archive flag set (DOS/Windows only)
+ FA_ALL - Match all attributes
+Do not use any other flags from DOS/Windows or your code will not compile on
+another platform.
+FA_RDONLY is for directory entries with read-only flag on DOS-like systems or
+unwritable by current user on Unix-like systems. Hidden files are directory
+entries that have the hidden flag set (DOS/Windows) or have names starting with
+'.' (UNIX, excluding '.' and '..').
+Flags can be combined using '|' (binary OR operator).
+
+
+When passed to the functions as the 'attrib' parameter, these flags
+represent an upper set in which the actual flag set of a matching file must
+be included. That is, in order for a file to be matching, its attributes
+may contain any of the specified flags but must not contain any of the
+unspecified flags. In other words, you explictly exclude the flags that you
+do not specify. Thus if you pass 'FA_DIREC | FA_RDONLY', normal files
+and directories will be included as well as read-only files and
+directories, but not hidden files and directories. Similarly, if you pass
+'FA_ARCH' then both archived and non-archived files will be included. If
+FA_NONE is passed all attributes are excluded and only files with no attributes
+are returned. Conversely, if you pass FA_ALL, no attributes are excluded so all
+files are returned (which is what you would usually want).
+
+
+Functions which accept wildcards as file names support the meta characters
+`*' (which means, zero or any quantity of characters) and `?' (which means
+any character, but only one).
+
+
+ Fills `buf' with the full path to the current executable, writing at most
+ `size' bytes. This generally comes from `argv[0]' but on Unix systems it
+ tries to get the information from the `/proc' filesystem first, searching
+ the directories specified in `$PATH' if necessary. If this fails too, it
+ tries to find the executable name from the output of the `ps' command,
+ using `argv[0]' only as a last resort if all other options fail. Example:
+
+ Converts the filename stored in `path' to a standardised case. On DOS
+ platforms, they will be entirely uppercase. On other platforms this
+ function doesn't do anything. Example:
+
+ Converts all the directory separators in the filename stored in `path' to
+ a standard character. On DOS and Windows platforms, this is a backslash.
+ On most other platforms this is a slash. Example:
+
+ char buf[200] = "c:/dos\\backup/weirdo\\test";
+ ...
+ fix_filename_slashes(buf);
+ /* Under DOS we would have c:\dos\backup\weirdo\test.
+ Under Unix we would have c:/dos/backup/weirdo/test. */
+
Return value:
+ Returns a copy of the `path' parameter.
+
+
+
+ Converts any filename into its canonical form, i.e. the minimal absolute
+ filename describing the same file and fixing incorrect forward/backward
+ slashes for the current platform, storing at most `size' bytes into the
+ `dest' buffer. You can use the same buffer both as input and output
+ because Allegro internally works on a copy of the input before touching
+ `dest'. Example:
+
+ char buf[256];
+ ...
+ canonicalize_filename(buf, "~/../s22/..\\t3st///hi.c",
+ sizeof(buf));
+ /* Running this under Unix would
+ return: /home/t3st/hi.c */
+
+ Note that this function won't work as expected if the path to canonicalize
+ comes from another platform (eg. a "c:\something" path will canonicalize
+ into something really wrong under Unix: "/current/path/c:/something").
+
Return value:
+ Returns a copy of the `dest' parameter.
+
+
+
+ Makes an absolute filename from an absolute path and a relative filename,
+ storing at most `size' bytes into the `dest' buffer. This is like calling
+ replace_filename() and then canonicalize_filename(). Example:
+
+ char buf[256];
+ ...
+ make_absolute_filename(buf, "/usr/games/",
+ "../temp.txt", sizeof(buf));
+ /* This would create /usr/temp.txt */
+
Return value:
+ Returns a copy of the `dest' parameter.
+
+
+
+ Attempts to make a relative filename from an absolute path and an absolute
+ filename, storing at most `size' bytes into the `dest' buffer. This
+ function won't work if the paths are not canonical under the current
+ platform (see canonicalize_filename()). Also, `dest' cannot be used as
+ input value for `path' or `filename'. Example:
+
Return value:
+ Returns a copy of the `dest' parameter if it succeeds or NULL if it fails
+ (eg. under DOS, one path starts with "C:\" and another with "A:\").
+
+
+
+ Returns TRUE if the filename is relative or FALSE if it is absolute. Note
+ that an absolute filename under DOS (with a device separator) will be
+ considered as relative under Unix, because there absolute paths always
+ start with a slash.
+
+
+
+ Replaces the specified path+filename with a new filename tail, storing
+ at most `size' bytes into the `dest' buffer. You can use the same buffer
+ both as input and output because Allegro internally works on a copy of
+ the input before touching `dest'. Example:
+
+ Replaces the specified filename+extension with a new extension tail,
+ storing at most `size' bytes into the `dest' buffer. If the filename
+ doesn't have any extension at all, `ext' will be appended to it, adding
+ a dot character if needed. You can use the same buffer both as input and
+ output because Allegro internally works on a copy of the input before
+ touching `dest'. Example:
+
+ Concatenates the specified filename onto the end of the specified path,
+ storing at most `size' bytes into the `dest' buffer. If `path' doesn't
+ have a trailing path separator, the function will append one if needed.
+ You can use the same buffer both as input and output because Allegro
+ internally works on a copy of the input before touching `dest'. Example:
+
+ Finds out the filename portion of a completely specified file path. Both
+ `\' and `/' are recognized as directory separators under DOS and Windows.
+ However, only `/' is recognized as directory separator under other
+ platforms. Example:
+
+ Note that Allegro won't perform any IO operations during the verification.
+ This means that if you have `/a/path/like/this/', which doesn't have a
+ filename, the function will return a pointer to the trailing null
+ character. However, if you have `/a/path/like/this', Allegro will return
+ a pointer to `this', even if it is a valid directory.
+
Return value:
+ Returns a pointer to the portion of `path' where the filename starts, or
+ the beginning of `path' if no valid filename is found (eg. you are
+ processing a path with backslashes under Unix).
+
+
+
Return value:
+ Returns a pointer to the portion of `filename' where the extension starts,
+ or a pointer to the trailing null character if there is no filename or it
+ doesn't have extension.
+
+
+
+ If the last character of the filename is not a `\', `/', `#' or a device
+ separator (ie. `:' under DOS), this routine will concatenate either a `\'
+ or `/' on to it (depending on the platform). Note: ignore the function
+ name, it's out of date.
+
+
+
int file_exists(const char *filename, int attrib, int *aret);
+ Checks whether a file matching the given name and attributes (see
+ beginning of this chapter) exists. If `aret' is not NULL, it will be set
+ to the attributes of the matching file. Example:
+
+ /* Check for a normal file. */
+ if (file_exists("franken.dat", 0, NULL))
+ allegro_message("It is alive!\n");
+
Return value:
+ Returns non-zero if the file exists, or zero if it doesn't or the
+ specified attributes mask it out.
+
+
+
+ Shortcut version of file_exists(), which checks for normal files, which
+ may have the archive or read-only bits set, but are not hidden,
+ directories, system files, etc.
+
Return value:
+ Returns non-zero if the file exists, or zero if it doesn't.
+
+
+
+ Returns the size of a file, in bytes. If the file does not exist or an
+ error occurs, it will return zero and store the system error code in
+ errno.
+
+
+
+ Returns the modification time (number of seconds since 00:00:00 GMT
+ 1/1/1970) of a file. If the file does not exist or an error occurs, it
+ will return zero and store the system error code in errno.
+
+
+
+ Removes a file from the disk. You can't delete directories, though.
+
Return value:
+ Returns zero on success, non-zero on failure.
+
+
+
int for_each_file_ex(const char *name, int in_attrib, int out_attrib,
+ int (*callback)(const char *filename, int attrib,
+ void *param), void *param);
+ Finds all the files on disk which match the given wildcard specification
+ and file attributes, and executes callback() once for each. Basically, this
+ is a convenient wrapper around al_findfirst(), al_findnext() and
+ al_findclose(). `in_attrib' is a bitmask specifying the attributes the
+ files must carry, `out_attrib' is a bitmask specifying the attributes the
+ files must not carry; attributes which are not specified in either bitmasks
+ are not taken into account for deciding whether callback() is invoked or
+ not.
+
+
+ The callback function will be passed three arguments: the first is a string
+ which contains the completed filename (exactly the same string you passed
+ to for_each_file_ex() but with meta characters), the second is the actual
+ attributes of the file, and the third is a void pointer which is simply a
+ copy of `param' (you can use this for whatever you like). The callback must
+ return zero to let the enumeration proceed, or any non-zero value to stop
+ it. If an error occurs, the error code will be stored in `errno' but the
+ enumeration won't stop. Example:
+
+ Low-level function for searching files. This function finds the first
+ file which matches the given wildcard specification and file attributes
+ (see above). The information about the file (if any) will be put in the
+ al_ffblk structure which you have to provide. The al_ffblk structure
+ looks like:
+
+ struct al_ffblk
+ {
+ int attrib; - actual attributes of the file found
+ time_t time; - modification time of file
+ char name[512]; - name of file
+ };
+
+ There is some other stuff in the structure as well, but it is there for
+ internal use only. Example:
+
+ struct al_ffblk info;
+
+ if (al_findfirst("*.pcx", &info, FA_ALL) != 0) {
+ /* Tell user there are no PCX files. */
+ return;
+ }
+
Return value:
+ The function returns non-zero if no match is found or if an error occurred
+ and, in the latter case, sets `errno' accordingly. It returns zero if a
+ match is found, allocating some memory for internal use in the structure.
+ Therefore you have to close your search when you are finished to avoid
+ memory leaks in your program.
+
+
+
+ This finds the next file in a search started by al_findfirst(). Example:
+
+ if (al_findfirst("*.pcx", &info, 0) != 0)
+ return;
+
+ do {
+ /* Do something useful here with info.name. */
+ } while (al_findnext(&info) == 0);
+
+ al_findclose(&info);
+
Return value:
+ Returns zero if a match is found, non-zero if none is found or if an
+ error occurred and, in the latter case, sets errno accordingly.
+
+
+
+ This closes a previously opened search with al_findfirst(). You need to
+ call this on all successfully opened searches to avoid memory leaks in
+ your program.
+
+
+
+ Searches for a support file, eg. `allegro.cfg' or `language.dat'. Passed a
+ resource string describing what you are looking for, along with extra
+ optional information such as the default extension, what datafile to look
+ inside, what the datafile object name is likely to be, any special
+ environment variable to check, and any subdirectory that you would like
+ to check as well as the default location, this function looks in a hell
+ of a lot of different places :-). Pass NULL for the parameters you are not
+ using.
+
+
+ Check the documentation chapter specific to your platform for information
+ on additional paths this function might search for. Also, don't forget
+ about set_allegro_resource_path() to extend the searches. Example:
+
+ char path[256];
+ int ret;
+ ret = find_allegro_resource(path, "scores.cfg", NULL, NULL,
+ NULL, NULL, NULL, sizeof(path));
+ if (ret == 0) {
+ /* Found system wide scores file. */
+ } else {
+ /* No previous scores, create our own file. */
+ }
+
Return value:
+ Returns zero on success, and stores a full path to the file (at most size
+ bytes) into the dest buffer.
+
+
+
+ Sometimes Allegro doesn't look in enough places to find a resource. For
+ those special cases, you can call this function before loading your
+ resource with additional paths to search for. You set up the priorities,
+ higher numbers are searched for first. To modify an already setup path,
+ call this function with the same priority and the new path. To remove an
+ already setup path, call this function with the priority of the path and
+ NULL as the path parameter. Example:
+
+ These custom paths will be valid until you call allegro_exit(). You can
+ call this function before install_allegro(), but after set_uformat() if
+ you want to use a text encoding format other than the default.
+
Return value:
+ Returns non-zero on success, zero if the path could not be added or you
+ wanted to remove a path and the priority used didn't have any associated
+ path. Modification of existing paths always succeeds.
+
+
+
+ Sets the encryption password to be used for all read/write operations
+ on files opened in future using Allegro's packfile functions (whether
+ they are compressed or not), including all the save, load and config
+ routines. Files written with an encryption password cannot be read
+ unless the same password is selected, so be careful: if you forget the
+ key, nobody can make your data come back again! Pass NULL or an empty
+ string to return to the normal, non-encrypted mode. If you are using
+ this function to prevent people getting access to your datafiles, be
+ careful not to store an obvious copy of the password in your executable:
+ if there are any strings like "I'm the password for the datafile", it
+ would be fairly easy to get access to your data :-)
+
+
+ Note #1: when writing a packfile, you can change the password to whatever
+ you want after opening the file, without affecting the write operation.
+ On the contrary, when writing a sub-chunk of a packfile, you must make
+ sure that the password that was active at the time the sub-chunk was
+ opened is still active before closing the sub-chunk. This is guaranteed
+ to be true if you didn't call the packfile_password() routine in the
+ meantime. Read operations, either on packfiles or sub-chunks, have no
+ such restriction.
+
+
+ Note #2: as explained above, the password is used for all read/write
+ operations on files, including for several functions of the library that
+ operate on files without explicitly using packfiles (e.g. load_bitmap()).
+ The unencrypted mode is mandatory in order for those functions to work.
+ Therefore remember to call packfile_password(NULL) before using them if
+ you previously changed the password. As a rule of thumb, always call
+ packfile_password(NULL) when you are done with operations on packfiles.
+ The only exception to this is custom packfiles created with
+ pack_fopen_vtable().
+
+
+
+ Opens a file according to mode, which may contain any of the flags:
+
+ `r' - open file for reading.
+
+ `w' - open file for writing, overwriting any existing data.
+
+ `p' - open file in packed mode. Data will be compressed as it is
+ written to the file, and automatically uncompressed during read
+ operations. Files created in this mode will produce garbage if
+ they are read without this flag being set.
+
+ `!' - open file for writing in normal, unpacked mode, but add the
+ value F_NOPACK_MAGIC to the start of the file, so that it can
+ later be opened in packed mode and Allegro will automatically
+ detect that the data does not need to be decompressed.
+
+ Instead of these flags, one of the constants F_READ, F_WRITE,
+ F_READ_PACKED, F_WRITE_PACKED or F_WRITE_NOPACK may be used as the mode
+ parameter.
+
+
+ The packfile functions also understand several "magic" filenames that are
+ used for special purposes. These are:
+
+ `#' - read data that has been appended to your executable file with
+ the exedat utility, as if it was a regular independent disk file.
+
+ `filename.dat#object_name' - open a specific object from a datafile,
+ and read from it as if it was a regular file. You can treat nested
+ datafiles exactly like a normal directory structure, for example
+ you could open `filename.dat#graphics/level1/mapdata'.
+
+ `#object_name' - combination of the above, reading an object from a
+ datafile that has been appended onto your executable.
+
+ With these special filenames, the contents of a datafile object or
+ appended file can be read in an identical way to a normal disk file, so
+ any of the file access functions in Allegro (eg. load_pcx() and
+ set_config_file()) can be used to read from them. Note that you can't
+ write to these special files, though: the fake file is read only. Also,
+ you must save your datafile uncompressed or with per-object compression
+ if you are planning on loading individual objects from it (otherwise
+ there will be an excessive amount of seeking when it is read).
+
+
+ Finally, be aware that the special Allegro object types aren't the same
+ format as the files you import the data from. When you import data like
+ bitmaps or samples into the grabber, they are converted into a special
+ Allegro-specific format, but the `#' marker file syntax reads the objects
+ as raw binary chunks. This means that if, for example, you want to use
+ load_pcx() to read an image from a datafile, you should import it as a
+ binary block rather than as a BITMAP object.
+
+
Return value:
+ On success, pack_fopen() returns a pointer to a PACKFILE structure, and on
+ error it returns NULL and stores an error code in `errno'. An attempt to
+ read a normal file in packed mode will cause `errno' to be set to EDOM.
+
+
+
+ Creates a new packfile structure that uses the functions specified in
+ the vtable instead of the standard functions. The data pointer by `vtable'
+ and `userdata' must remain available for the lifetime of the created
+ packfile.
+
+
+ While the created packfile structure can be used with other Allegro
+ functions, there are two limitations. First, opening chunks using
+ pack_fopen_chunk() on top of the returned packfile is not possible at this
+ time. And packfile_password() does not have any effect on packfiles opened
+ with pack_fopen_vtable().
+
Return value:
+ On success, it returns a pointer to a PACKFILE structure, and on error it
+ returns NULL and stores an error code in `errno'.
+
+
+
+ Closes the stream `f' previously opened with pack_fopen() or
+ pack_fopen_vtable(). After you have closed the stream, performing
+ operations on it will yield errors in your application (e.g. crash it) or
+ even block your OS.
+
Return value:
+ Returns zero on success. On error, returns an error code which is also
+ stored in `errno'. This function can fail only when writing to files: if
+ the file was opened in read mode, it will always succeed.
+
+
+
+ Moves the position indicator of the stream `f'. Unlike the standard fseek()
+ function, this only supports forward movements relative to the current
+ position and in read-only streams, so don't use negative offsets. Note that
+ seeking is very slow when reading compressed files, and so should be
+ avoided unless you are sure that the file is not compressed. Example:
+
+ input_file = pack_fopen("data.bin", "r");
+ if (!input_file)
+ abort_on_error("Couldn't open binary data!");
+ /* Skip some useless header before reading data. */
+ pack_fseek(input_file, 32);
+
Return value:
+ Returns zero on success or a negative number on error, storing the error
+ code in `errno'.
+
+
+
+ Finds out if you have reached the end of the file. It does not wait for you
+ to attempt to read beyond the end of the file, contrary to the ISO C feof()
+ function. The only way to know whether you have read beyond the end of the
+ file is to check the return value of the read operation you use (and be
+ wary of pack_*getl() as EOF is also a valid return value with these
+ functions).
+
Return value:
+ Returns non-zero if you are at the end of the file, zero otherwise.
+
+
+
+ Since EOF is used to report errors by some functions, it's often better to
+ use the pack_feof() function to check explicitly for end of file and
+ pack_ferror() to check for errors. Both functions check indicators that
+ are part of the internal state of the stream to detect correctly the
+ different situations.
+
Return value:
+ Returns nonzero if the error indicator for the stream is set, meaning
+ that an error has occurred during a previous operation on the stream.
+
+
+
Return value:
+ Returns the number of bytes read, which will be less than `n' if EOF is
+ reached or an error occurs. Error codes are stored in errno.
+
+
+
+ Reads a line from the stream `f', storing it at location pointed to by
+ `p'. Stops when a linefeed is encountered, or `max' bytes have been read.
+ The end of line is handled by detecting the right combination of characters
+ for the platform. This supports CR-LF (DOS/Windows), LF (Unix), and CR
+ (Mac) formats. However, the trailing carriage return is not included in the
+ returned string, in order to provide easy code portability across
+ platforms. If you need the carriage return, use pack_fread() and/or
+ pack_getc() instead. Example:
+
+ Writes a string to the stream `f'. The input string is converted from the
+ current text encoding format to UTF-8 before writing. Newline characters
+ are written as `\r\n' on DOS and Windows platforms. If you don't want this
+ behaviour, use pack_fwrite() and/or pack_putc() instead.
+
Return value:
+ Returns zero on success or a negative number on error.
+
+
+
+ Opens a sub-chunk of a file. Chunks are primarily intended for use by the
+ datafile code, but they may also be useful for your own file routines. A
+ chunk provides a logical view of part of a file, which can be compressed
+ as an individual entity and will automatically insert and check length
+ counts to prevent reading past the end of the chunk. The PACKFILE
+ parameter is a previously opened file, and `pack' is a boolean parameter
+ which will turn compression on for the sub-chunk if it is non-zero.
+ Example:
+
+ PACKFILE *output = pack_fopen("out.raw", "w!");
+ ...
+ /* Create a sub-chunk with compression. */
+ output = pack_fopen(chunk(output, 1);
+ if (!output)
+ abort_on_error("Error saving data!");
+ /* Write some data to the sub-chunk. */
+ ...
+ /* Close the sub-chunk, recovering parent file. */
+ output = pack_fclose_chunk(output);
+
+ The data written to the chunk will be prefixed with two length counts
+ (32-bit, a.k.a. big-endian). For uncompressed chunks these will both be
+ set to the size of the data in the chunk. For compressed chunks (created
+ by setting the `pack' flag), the first length will be the raw size of the
+ chunk, and the second will be the negative size of the uncompressed data.
+
+
+ This sequence will read the length counts created when the chunk was
+ written, and automatically decompress the contents of the chunk if it
+ was compressed. The length will also be used to prevent reading past the
+ end of the chunk (Allegro will return EOF if you attempt this), and to
+ automatically skip past any unread chunk data when you call
+ pack_fclose_chunk().
+
+
+ Chunks can be nested inside each other by making repeated calls to
+ pack_fopen_chunk(). When writing a file, the compression status is
+ inherited from the parent file, so you only need to set the pack flag if
+ the parent is not compressed but you want to pack the chunk data. If the
+ parent file is already open in packed mode, setting the pack flag will
+ result in data being compressed twice: once as it is written to the
+ chunk, and again as the chunk passes it on to the parent file.
+
Return value:
+ Returns a pointer to the sub-chunked PACKFILE, or NULL if there was some
+ error (eg. you are using a custom PACKFILE vtable).
+
+
+
+ Closes a sub-chunk of a file, previously obtained by calling
+ pack_fopen_chunk().
+
Return value:
+ Returns a pointer to the parent of the sub-chunk you just closed. Returns
+ NULL if there was some error (eg. you tried to close a PACKFILE which
+ wasn't sub-chunked).
+
+
+
+Datafiles are created by the grabber utility (see grabber.txt for more
+information), and have a `.dat' extension. They can contain bitmaps, palettes,
+fonts, samples, MIDI music, FLI/FLC animations, and any other binary data that
+you import. You could distribute your bitmaps and samples in a myriad of
+separate files, but packing them in a few `.dat' binaries has a few
+advantages:
+
+ On some platforms loading a single big datafile at once is faster than
+ loading individual resources one by one.
+
+ Instead of several loops for your resources, you can write a single line of
+ code with just a single point of failure to take care of.
+
+ You can potentially reduce the size of your data by enabling compression
+ on your datafiles. Less download time for your end users, less wait during
+ loading screens!
+
+ If you don't need to load the whole datafile at once, you can still enable
+ individual file compression. It is slightly worse than global compression,
+ but it is very fast with loading times because Allegro can easily seek
+ inside the datafile to find a specific object.
+
+ Even without encryption, most end users of your application won't be able
+ to look at or modify the resources for your game. A missing sound file or
+ a modified bitmap could potentially crash the game if you haven't
+ considered this in your loading code!
+
+ It looks much more professional and convenient to distribute levels! For
+ example, if you found a bug in a level of your game, just distribute your
+ new `level4.dat' and tell users to overwrite their old version.
+
+Allegro allows you to load datafiles once and forget about them. But if you
+have many levels it can be wise to load only the resources required for the
+current level. You can accomplish the later by separating levels in different
+datafiles, or using functions like load_datafile_object() to avoid loading
+everything at once. You can even read directly from a specific datafile object
+with the pack_fopen() function.
+
+
+On some platforms you can attach datafiles to your binary, potentially
+reducing your game distribution down to a single executable file. Try the
+example exexedat on your platform to see if this is possible. However, this
+is not recommended for big programs: a single update to your code or binary
+data would force end users to download again a potentially big file, no matter
+how small your change is. The same warning goes for the tools dat2s or dat2c,
+which convert datafiles into assembler and C code respectively, prepared to be
+included directly in your binary.
+
+
+Remember that with Allegro truecolor images can only be loaded after you have
+set a graphics mode. This is true for datafiles too. Load all your data after
+you have set the graphics mode, otherwise the pixel format (RGB or BGR) will
+not be known and the datafile may be converted wrongly. Oh, and read carefully
+the warning of fixup_datafile() if you plan on switching resolutions during
+runtime.
+
+
+Note: even though Allegro datafiles provide encryption, you should consider
+it weak, so don't plan on hiding there the plans for a Death Star or
+something. Determinate knowledgeable users will be able to rip your resources
+no matter how hard you try to hide them! Use the encryption only as a slight
+deterrent towards unwanted tampering of your data. How to crack an encrypted
+datafile is left as an exercise to the reader, though.
+
+
+Using datafiles once they are loaded is quite simple: you access the elements
+of the DATAFILE as a normal array. Read below the section "Using datafiles"
+below for several examples on how to access their data.
+
+
+ Loads a datafile into memory in one go. If the datafile has been encrypted,
+ you must first call packfile_password() to set the appropriate key. If the
+ datafile contains truecolor graphics, you must set the video mode or call
+ set_color_conversion() before loading it. Example:
+
+ /* Load the resources for our game. */
+ DATAFILE *dat = load_datafile("game.dat");
+ if (!dat)
+ abort_on_error("Couldn't load sound resources!");
+ /* Use resources. */
+ ...
+ /* Destroy them when we don't need them any more. */
+ unload_datafile(dat);
+
Return value:
+ Returns a pointer to the DATAFILE, or NULL on error. Remember to free this
+ DATAFILE later to avoid memory leaks.
+
+
+
+ Loads a datafile into memory, calling the specified hook function once for
+ each object in the file, passing it a pointer to the object just read. You
+ can use this to implement very simple loading screens where every time the
+ hook is called, the screen is updated to let the user know your program is
+ still loading from disk:
+
+ void load_callback(DATAFILE *dat_obj)
+ {
+ static const char indicator[] = "-\\|/-.oOXOo.";
+ static int current = 0;
+
+ /* Show a different character every time. */
+ textprintf_ex(screen, font, 0, 0, makecol(0, 0, 0),
+ makecol(255, 255, 255), "%c Loading %c",
+ indicator[current], indicator[current]);
+ /* Increase index and check if we need to reset it. */
+ current++;
+ if (!indicator[current])
+ current = 0;
+ }
+ ...
+ dat = load_datafile_callback("data.dat", load_callback);
+
Return value:
+ Returns a pointer to the DATAFILE or NULL on error. Remember to free this
+ DATAFILE later to avoid memory leaks.
+
+
+
+ Loads a specific object from a datafile. This won't work if you strip the
+ object names from the file, and it will be very slow if you save the file
+ with global compression. Example:
+
+ /* Load only the music from the datafile. */
+ music_object = load_datafile_object("datafile.dat",
+ "MUSIC");
+ /* Play it and wait a moment for it. */
+ play_midi(music_object->dat);
+ ...
+ /* Destroy unneeded music. */
+ unload_datafile_object(music_object);
+
Return value:
+ Returns a pointer to a single DATAFILE element whose `dat' member points to
+ the object, or NULL if there was an error or there was no object with the
+ requested name. Remember to free this DATAFILE later to avoid memory leaks,
+ but use the correct unloading function!
+
+
+
+ Searches an already loaded datafile for an object with the specified
+ name. In the name you can use `/' and `#' separators for nested datafile
+ paths. Example:
+
Return value:
+ Returns a pointer to a single DATAFILE element whose `dat' member points to
+ the object, or NULL if the object could not be found.
+
+
+
+ Creates an index for a datafile, to speed up loading single objects out of
+ it. This is mostly useful for big datafiles, which you don't want to load as
+ a whole. The index will store the offset of all objects inside the datafile,
+ and then you can load it quickly with "load_datafile_object_indexed" later.
+ Use destroy_datafile_index to free the memory used by it again.
+
+
+ Note: If the datafile uses global compression, there is no performance gain
+ from using an index, because seeking to the offset still requires to
+ uncompress the whole datafile up to that offset.
+ Example:
+
+ This loads a single object, using the index created previously with
+ create_datafile_index. See create_datafile_index for an example.
+
Return value:
+ Returns a pointer to a single DATAFILE element whose "dat" member points to
+ the object, or NULL if the object could not be loaded.
+
+
+
+ If you are using compiled datafiles (produced by the dat2s and dat2c
+ utilities) on a platform that doesn't support constructors (currently any
+ non GCC-based platform), or if the datafiles contain truecolor images, you
+ must call this function once after your set the video mode that you will
+ be using. This will ensure the datafiles are properly initialised in the
+ first case and convert the color values into the appropriate format in
+ the second case. It handles flipping between RGB and BGR formats, and
+ converting between different color depths whenever that can be done
+ without changing the size of the image (ie. changing 15<->16-bit
+ hicolor for both bitmaps and RLE sprites, and 24<->32-bit truecolor
+ for RLE sprites).
+
+
+ Note that you can only call this once and expect it to work correctly,
+ because after the call the DATAFILE you fixed up is permanently converted
+ to whatever is the current component ordering for your screen mode. If you
+ call fixup_datafile again, the function assumes you have a freshly loaded
+ datafile. It cannot "undo" the previous conversion.
+
+
+ If your program supports changing resolution and/or color depth during
+ runtime, you have two choices: either call fixup_datafile() just once and
+ hope that the component ordering and bit depth doesn't change when the
+ screen mode changes (unlikely). Or, you can reload your datafiles when the
+ screen mode changes.
+
+
+
+ Every object or property in a datafile is identified by a 4 letter ID,
+ which can be created with this macro. For example, to access the NAME
+ property of a datafile object, you could use:
+
+In order to access the contents of a datafile, you will need to know where
+each object is located. The easiest way to do this is by integer index,
+using an automatically generated header file. With the grabber, type a name
+into the "Header:" field, and the object indexes will be written to this
+file whenever the datafile is saved. With the dat utility, use the '-h'
+option, eg. "dat filename.dat -h filename.h". The header will define C
+preprocessor symbols for each object in the datafile, for example:
+
+ #define SOME_DATA 0 /* DATA */
+ #define SOME_MORE_DATA 1 /* DATA */
+
+To prevent name conflicts, you can specify a prefix string for these
+definitions by typing it into the "Prefix:" field in the grabber or using
+the '-p' option to dat.
+
+
+To load a datafile into memory, call the function:
+
+This will load the entire file, returning a pointer to it, or NULL on error.
+When the data is no longer required, the entire thing can be destroyed by
+calling:
+
+When you load a datafile, you will obtain a pointer to an array of DATAFILE
+structures:
+
+ typedef struct DATAFILE
+ {
+ void *dat; - pointer to the actual data
+ int type; - object type ID
+ long size; - size of the data, in bytes
+ DATAFILE_PROPERTY *prop; - list of object properties
+ } DATAFILE;
+
+
+The only really important piece of information here is the `dat' field, which
+points to the contents of the object. What type of data this is will depend
+on the type of object: for bitmaps it will be an Allegro BITMAP structure,
+for RLE sprites an RLE_SPRITE, for fonts a FONT structure, etc. If you are
+programming in C you can pass this pointer directly to the relevant Allegro
+library functions, but if you are using C++ you will need to cast it to the
+appropriate type to prevent the compiler giving a warning.
+
+
+For example, if you have a datafile called `myfile.dat', which contains a
+bitmap called COOL_PICTURE, and you have used it to produce a header called
+`myfile.h', you could display the bitmap with the code:
+
+If a datafile contains nested child datafiles, the header will prefix the
+names of objects in the sub-files with the name of their parent datafile. It
+will also define a count of the number of objects in the child file, which
+may be useful if for example the child datafile contains several bitmaps
+which form a 'run' animation, and you want your code to automatically
+adjust to the number of frames in the datafile.
+
+
+The main datafile contains three objects (NESTED_FILE, SOME_DATA, and
+SOME_MORE_DATA) with consecutive indexes, while the child datafile contains
+the two objects A_BITMAP and A_FONT. To access these objects you need to
+reference both the parent and child datafiles, eg:
+
+This will return a pointer to the property string if it can be found, and an
+empty string (not null!) if it does not exist. One possible use of this
+function is to locate objects by name, rather than using the indexes from a
+header file. The datafile array is ended by an object of type DAT_END, so to
+search the datafile dat for the object "my_object" you could use the code:
+
+ const int name_type = DAT_ID('N','A','M','E');
+ for (i=0; dat[i].type != DAT_END; i++) {
+ if (stricmp(get_datafile_property(dat+i, name_type),
+ "my_object") == 0) {
+ /* found the object at index i */
+ }
+ }
+ /* not found... */
+
+If you prefer to access objects by name rather than index number, you can
+use the function:
+
+This will search an already loaded datafile for an object with the specified
+name, returning a pointer to it, or NULL if the object cannot be found. It
+understands '/' and '#' separators for nested datafile paths.
+
+
+It is also possible to selectively load individual objects from a datafile,
+with the function:
+
+This searches the datafile for an object with the specified name, so
+obviously it won't work if you strip the name properties out of the file.
+Because this function needs to seek through the data, it will be extremely
+slow if you have saved the file with global compression. If you are planning
+to load objects individually, you should save the file uncompressed or with
+individual compression per-object. Because the returned datafile points to a
+single object rather than an array of objects, you should access it with the
+syntax datafile->dat, rather than datafile[index].dat, and when you are done
+you should free the object with the function:
+
+Alternatively, the packfile functions can open and read directly from the
+contents of a datafile object. You do this by calling pack_fopen() with a
+fake filename in the form "filename.dat#object_name". The contents of the
+object can then be read in an identical way to a normal disk file, so any of
+the file access functions in Allegro (eg. load_pcx() and set_config_file())
+can be used to read from datafile objects. Note that you can't write to
+datafiles in this way: the fake file is read only. Also, you should save the
+file uncompressed or with per-object compression if you are planning on
+using this feature. Finally, be aware that the special Allegro object types
+aren't the same format as the files you import the data from, so if for
+example you want to use load_pcx to read an image from a datafile, you
+should import it as a binary data chunk rather than as a BITMAP object.
+
+
+If you have appended a datafile to the end of your executable with the
+exedat utility, use load_datafile("#") to read the entire thing into memory,
+load_datafile_object("#", "object_name") to load a specific object, and
+pack_fopen("#object_name", F_READ) to read one of the objects directly with
+your own code. Note that unless you use the previous functions to load the
+appended data, the OS will not load it into memory just because you are
+running the program, so you shouldn't have problems attaching datafiles to
+your binary larger than the available system memory.
+
+
+By default, all graphic objects loaded from a datafile will be converted
+into the current color depth. This conversion may be both lossy and very
+slow, particularly when reducing from truecolor to 256 color formats, so you
+may wish to disable it by calling set_color_conversion(COLORCONV_NONE) or
+set_color_conversion(COLORCONV_PARTIAL) before your call to load_datafile().
+
+
+
+
+Some of the objects in a datafile, for example palettes and FLI animations,
+are simply treated as blocks of binary data, but others are loaded into
+special formats such as bitmap structures or compiled sprites. It is
+possible to extend the datafile system to support your own custom object
+types, eg. map objects for a tile based engine, or level data for a platform
+game. Obviously the grabber has no way of understanding this data, but it
+will allow you to import binary data from external files, so you can grab
+information produced by your own utilities. If you are happy with the data
+being loaded as a simple binary block, that is all you need to do, but if
+you need to load it into a specific structure, read on...
+
+
+Your custom objects must be given a unique type ID, which is formed from
+four ASCII characters (by convention all uppercase A-Z). If you don't use
+all four characters, the string should be padded with spaces (ASCII 32). You
+should use this ID when creating the objects in the grabber (select
+New/Other and type in the ID string), and in your code you should define an
+identifier for the type, eg:
+
+You then need to write functions for loading and destroying objects of this
+type, in the form:
+
+ void *load_mapdata(PACKFILE *f, long size)
+ {
+ /* Allegro will call this function whenever an object of your custom
+ * type needs to be loaded from a datafile. It will be passed a
+ * pointer to the file from which the data is to be read, and the size
+ * of the object in bytes. It should return a pointer to the loaded
+ * data, which will be stored in the dat field of the datafile object
+ * structure, or NULL if an error occurs. The file will have been
+ * opened as a sub-chunk of the main datafile, so it is safe to read
+ * past the end of the object (if you attempt this, Allegro will
+ * return EOF), and it is also safe to return before reading all the
+ * data in the chunk (if you do this, Allegro will skip any unused
+ * bytes before starting to read the next object). You should _not_
+ * close the file when you are done: this will be handled by the
+ * calling function. To clarify how all this works, here's an example
+ * implementation of a null-terminated string object:
+ */
+
+ #define MAX_LEN 256
+
+ char buf[MAX_LEN];
+ char *p;
+ int i, c;
+
+ for (i=0; i<;MAX_LEN-1; i++) {
+ if ((c = pack_getc(f)) == EOF)
+ break;
+
+ buf[i] = c;
+ }
+
+ buf[i] = 0;
+
+ p = malloc(i+1);
+ strcpy(p, buf);
+
+ return p;
+ }
+
+ void destroy_mapdata(void *data)
+ {
+ /* Allegro will call this function whenever an object of your custom
+ * type needs to be destroyed. It will be passed a pointer to the
+ * object (as returned by the load function), and should free whatever
+ * memory the object is using. For example, the simple string object
+ * returned by the above loader could be destroyed with the code:
+ */
+
+ if (data)
+ free(data);
+ }
+
+Finally, before you load your datafile you must tell Allegro about the
+custom format, by calling:
+
+It is also possible to integrate support for custom object types directly
+into the grabber and dat utilities, by copying some special files into the
+tools/plugins directory. This can be used to add whole new object types and
+menu commands, or to provide additional import/export routines for the
+existing formats. See `tools/plugins/plugins.txt' for an overview of how to
+write your own grabber plugins.
+
+
+
+
radtofix_r — Constant to convert radians to fixed point angles.
+
+
+
+Allegro provides some routines for working with fixed point numbers, and
+defines the type `fixed' to be a signed 32-bit integer. The high word is
+used for the integer part and the low word for the fraction, giving a range
+of -32768 to 32767 and an accuracy of about four or five decimal places.
+Fixed point numbers can be assigned, compared, added, subtracted, negated and
+shifted (for multiplying or dividing by powers of two) using the normal
+integer operators, but you should take care to use the appropriate conversion
+routines when mixing fixed point with integer or floating point values.
+Writing `fixed_point_1 + fixed_point_2' is OK, but `fixed_point + integer' is
+not.
+
+
+Unfortunately the only advantage of fixed point math routines is that you
+don't require a floating point coprocessor to use them. This was great in the
+time period of i386 and i486 machines, but stopped being so useful with the
+coming of the Pentium class of processors. From Pentium onwards, CPUs have
+increased their strength in floating point operations, equaling or even
+surpassing integer math performance.
+
+
+Depending on the type of operations your program may need, using floating
+point types may be faster than fixed types if you are targeting a specific
+machine class. Allegro comes with a test program in the `allegro/tests'
+directory. Its `Misc' menu contains a basic profile test which can give you
+an idea of the speed difference between fixed and float types for a few basic
+operations on your machine. However, don't forget to profile your program in
+real life conditions, tight loop benchmarks are after all artificial.
+
+
+Fixed point math is considered "add-on" material and is kept only for
+backwards compatibility. Whenever a future release of Allegro breaks backwards
+compatibility, fixed point math will likely be moved to a separate add-on
+package for the very few users who still find it convenient and useful, and
+Allegro functions using fixed point math will use other types.
+
+
+ Converts an integer to fixed point. This is the same thing as x<<16.
+ Remember that overflows (trying to convert an integer greater than 32767)
+ and underflows (trying to convert an integer lesser than -32768) are not
+ detected even in debug builds! The values simply "wrap around". Example:
+
+ fixed number;
+ /* This conversion is OK. */
+ number = itofix(100);
+ ASSERT(fixtoi(number) == 100);
+ number = itofix(64000);
+ /* This check will fail in debug builds. */
+ ASSERT(fixtoi(number) == 64000);
+
Return value:
+ Returns the value of the integer converted to fixed point ignoring
+ overflows.
+
+
+
+ Converts fixed point to integer, rounding as required to the nearest
+ integer. Example:
+
+ int result;
+ /* This will put 33 into `result'. */
+ result = fixtoi(itofix(100) / 3);
+ /* But this will round up to 17. */
+ result = fixtoi(itofix(100) / 6);
+ Returns the greatest integer not greater than x. That is, it rounds
+ towards negative infinity. Example:
+
+ int result;
+ /* This will put 33 into `result'. */
+ result = fixfloor(itofix(100) / 3);
+ /* And this will round down to 16. */
+ result = fixfloor(itofix(100) / 6);
+ Returns the smallest integer not less than x. That is, it rounds towards
+ positive infinity. Example:
+
+ int result;
+ /* This will put 34 into `result'. */
+ result = fixceil(itofix(100) / 3);
+ /* This will round up to 17. */
+ result = fixceil(itofix(100) / 6);
+ Converts a floating point value to fixed point. Unlike itofix(), this
+ function clamps values which could overflow the type conversion, setting
+ `errno' to ERANGE in the process if this happens. Example:
+
+ Converts fixed point to floating point. Example:
+
+ float result;
+
+ /* This will put 33.33333 into `result'. */
+ result = fixtof(itofix(100) / 3);
+ /* This will put 16.66666 into `result'. */
+ result = fixtof(itofix(100) / 6);
+ A fixed point value can be multiplied or divided by an integer with the
+ normal `*' and `/' operators. To multiply two fixed point values, though,
+ you must use this function.
+
+
+ If an overflow occurs, `errno' will be set and the maximum possible value
+ will be returned, but `errno' is not cleared if the operation is
+ successful. This means that if you are going to test for overflow you
+ should set `errno=0' before calling fixmul(). Example:
+
+ fixed result;
+
+ /* This will put 30000 into `result'. */
+ result = fixmul(itofix(10), itofix(3000));
+ /* But this overflows, and sets `errno'. */
+ result = fixmul(itofix(100), itofix(3000));
+ ASSERT(!errno);
+
Return value:
+ Returns the clamped result of multiplying `x' by `y', setting `errno' to
+ ERANGE if there was an overflow.
+
+
+
+ A fixed point value can be divided by an integer with the normal `/'
+ operator. To divide two fixed point values, though, you must use this
+ function. If a division by zero occurs, `errno' will be set and the
+ maximum possible value will be returned, but `errno' is not cleared if the
+ operation is successful. This means that if you are going to test for
+ division by zero you should set `errno=0' before calling fixdiv(). Example:
+
+ fixed result;
+ /* This will put 0.06060 `result'. */
+ result = fixdiv(itofix(2), itofix(33));
+ /* This will put 0 into `result'. */
+ result = fixdiv(0, itofix(-30));
+ /* Sets `errno' and puts -32768 into `result'. */
+ result = fixdiv(itofix(-100), itofix(0));
+ ASSERT(!errno); /* This will fail. */
+
Return value:
+ Returns the result of dividing `x' by `y'. If `y' is zero, returns the
+ maximum possible fixed point value and sets `errno' to ERANGE.
+
+
+
+ Although fixed point numbers can be added with the normal '+' integer
+ operator, that doesn't provide any protection against overflow. If overflow
+ is a problem, you should use this function instead. It is slower than using
+ integer operators, but if an overflow occurs it will set `errno' and clamp
+ the result, rather than just letting it wrap. Example:
+
+ fixed result;
+ /* This will put 5035 into `result'. */
+ result = fixadd(itofix(5000), itofix(35));
+ /* Sets `errno' and puts -32768 into `result'. */
+ result = fixadd(itofix(-31000), itofix(-3000));
+ ASSERT(!errno); /* This will fail. */
+
Return value:
+ Returns the clamped result of adding `x' to `y', setting `errno' to ERANGE
+ if there was an overflow.
+
+
+
+ Although fixed point numbers can be subtracted with the normal '-' integer
+ operator, that doesn't provide any protection against overflow. If overflow
+ is a problem, you should use this function instead. It is slower than using
+ integer operators, but if an overflow occurs it will set `errno' and clamp
+ the result, rather than just letting it wrap. Example:
+
+ fixed result;
+ /* This will put 4965 into `result'. */
+ result = fixsub(itofix(5000), itofix(35));
+ /* Sets `errno' and puts -32768 into `result'. */
+ result = fixsub(itofix(-31000), itofix(3000));
+ ASSERT(!errno); /* This will fail. */
+
Return value:
+ Returns the clamped result of subtracting `y' from `x', setting `errno' to
+ ERANGE if there was an overflow.
+
+
+
+The fixed point square root, sin, cos, tan, inverse sin, and inverse cos
+functions are implemented using lookup tables, which are very fast but not
+particularly accurate. At the moment the inverse tan uses an iterative
+search on the tan table, so it is a lot slower than the others. Note that on
+machines with very good floating point processors using these functions could
+be slower in real life code due to cache misses: it may be faster to wait
+a few extra cicles for a floating point sine result rather than wait for the
+CPU to fetch the precalculated table from main memory. Always profile your
+code.
+
+
+Angles are represented in a binary format with 256 equal to a full circle,
+64 being a right angle and so on. This has the advantage that a simple
+bitwise 'and' can be used to keep the angle within the range zero to a full
+circle, eliminating all those tiresome 'if (angle >= 360)' checks.
+
+
+ This constant gives a ratio which can be used to convert a fixed point
+ number in binary angle format to a fixed point number in radians. Example:
+
+ fixed rad_angle, binary_angle;
+ /* Set the binary angle to 90 degrees. */
+ binary_angle = 64;
+ /* Now convert to radians (about 1.57). */
+ rad_angle = fixmul(binary_angle, fixtorad_r);
+ This constant gives a ratio which can be used to convert a fixed point
+ number in radians to a fixed point number in binary angle format. Example:
+
+ This function finds the sine of a value using a lookup table. The input
+ value must be a fixed point binary angle. Example:
+
+ fixed angle;
+ int result;
+
+ /* Set the binary angle to 90 degrees. */
+ angle = itofix(64);
+ /* The sine of 90 degrees is one. */
+ result = fixtoi(fixsin(angle));
+ ASSERT(result == 1);
+
Return value:
+ Returns the sine of a fixed point binary format angle. The return value
+ will be in radians.
+
+
+
+ This function finds the cosine of a value using a lookup table. The input
+ value must be a fixed point binary angle. Example:
+
+ fixed angle;
+ float result;
+
+ /* Set the binary angle to 45 degrees. */
+ angle = itofix(32);
+ /* The cosine of 45 degrees is about 0.7071. */
+ result = fixtof(fixcos(angle));
+ ASSERT(result > 0.7 && result < 0.71);
+
Return value:
+ Returns the cosine of a fixed point binary format angle. The return value
+ will be in radians.
+
+
+
+ This function finds the inverse sine of a value using a lookup table. The
+ input value must be a fixed point value. The inverse sine is defined only
+ in the domain from `-1' to `1'. Outside of this input range, the function
+ will set `errno' to EDOM and return zero. Example:
+
+ float angle;
+ fixed val;
+
+ /* Sets `val' to a right binary angle (`64'). */
+ val = fixasin(itofix(1));
+ /* Sets `angle' to 0.2405. */
+ angle = fixtof(fixmul(fixasin(ftofix(0.238)), fixtorad_r));
+ /* This will trigger the assert. */
+ val = fixasin(ftofix(-1.09));
+ ASSERT(!errno);
+
Return value:
+ Returns the inverse sine of a fixed point value, measured as fixed point
+ binary format angle, or zero if the input was out of the range. All return
+ values of this function will be in the range `-64' to `64'.
+
+
+
+ This function finds the inverse cosine of a value using a lookup table. The
+ input value must be a fixed point radian. The inverse cosine is defined
+ only in the domain from `-1' to `1'. Outside of this input range, the
+ function will set `errno' to EDOM and return zero. Example:
+
+ fixed result;
+
+ /* Sets `result' to binary angle 128. */
+ result = fixacos(itofix(-1));
+
Return value:
+ Returns the inverse sine of a fixed point value, measured as fixed point
+ binary format angle, or zero if the input was out of range. All return
+ values of this function will be in the range `0' to `128'.
+
+
+
+ This function finds the inverse tangent of a value using a lookup table.
+ The input value must be a fixed point radian. The inverse tangent is the
+ value whose tangent is `x'. Example:
+
+ fixed result;
+
+ /* Sets `result' to binary angle 13. */
+ result = fixatan(ftofix(0.326));
+
Return value:
+ Returns the inverse tangent of a fixed point value, measured as a fixed
+ point binary format angle.
+
+
+
+ This is a fixed point version of the libc atan2() routine. It computes the
+ arc tangent of `y / x', but the signs of both arguments are used to
+ determine the quadrant of the result, and `x' is permitted to be zero. This
+ function is useful to convert Cartesian coordinates to polar coordinates.
+ Example:
+
+ fixed result;
+
+ /* Sets `result' to binary angle 64. */
+ result = fixatan2(itofix(1), 0);
+ /* Sets `result' to binary angle -109. */
+ result = fixatan2(itofix(-1), itofix(-2));
+ /* Fails the assert. */
+ result = fixatan2(0, 0);
+ ASSERT(!errno);
+
Return value:
+ Returns the arc tangent of `y / x' in fixed point binary format angle,
+ from `-128' to `128'. If both `x' and `y' are zero, returns zero and sets
+ `errno' to EDOM.
+
+
+
+ Fixed point hypotenuse (returns the square root of `x*x + y*y'). This
+ should be better than calculating the formula yourself manually, since
+ the error is much smaller.
+
+
+
+If you are programming in C++ you can ignore all the above and use the fix
+class instead, which overloads a lot of operators to provide automatic
+conversion to and from integer and floating point values, and calls the
+above routines as they are required. You should not mix the fix class with
+the fixed typedef though, because the compiler will mistake the fixed values
+for regular integers and insert unnecessary conversions. For example, if x
+is an object of class fix, calling fixsqrt(x) will return the wrong result.
+You should use the overloaded sqrt(x) or x.sqrt() instead.
+
+
+On top of that, the Fix class may be slower than using directly the C
+functions because of implicit internal conversions from one type to another
+which you otherwise could avoid or minimise. Finally, this is the only bit
+of C++ in the whole Allegro library, and the developers are certainly going
+to move it into add-on space in the next version of Allegro which breaks
+source backwards compatibility.
+
+
+
+
+Allegro contains some 3d helper functions for manipulating vectors,
+constructing and using transformation matrices, and doing perspective
+projections from 3d space onto the screen. It is not, and never will be, a
+fully fledged 3d library (the goal is to supply generic support routines,
+not shrink-wrapped graphics code :-) but these functions may be useful for
+developing your own 3d code.
+
+
+Allegro uses a right-handed coordinate system, i.e. if you point the thumb
+of your right hand along the x axis, and the index finger along the y axis,
+your middle finger points in the direction of the z axis.
+
+
+Allegro's world coordinate system typically has the positive x axis right,
+the positive y axis up, and the positive z axis out of the screen. What
+all this means is this: Assume, the viewer is located at the origin (0/0/0)
+in world space, looks along the negative z axis (0/0/-1), and is oriented
+so up is along the positive y axis (0/1/0). Then something located at
+(100/200/-300) will be 100 to the right, 200 above, and 300 in front of the
+viewer. Just like in OpenGL. (Of course, both OpenGL and Allegro allow to
+use a different system.) Here's a short piece of code demonstrating the
+transformation pipeline of a point from world space to the screen.
+
+
+ /* First, set up the projection viewport. */
+ set_projection_viewport (0, 0, SCREEN_W, SCREEN_H);
+
+ /* Next, get a camera matrix, depending on the
+ * current viewer position and orientation.
+ */
+ get_camera_matrix_f (&m,
+ 0, 0, 0, /* Viewer position, in this case, 0/0/0. */
+ 0, 0, -1, /* Viewer direction, in this case along negative z. */
+ 0, 1, 0, /* Up vector, in this case positive y. */
+ 32, /* The FOV, here 45°. */
+ (float)SCREEN_W / (float)SCREEN_H)); /* Aspect ratio. */
+
+ /* Applying the matrix transforms the point 100/200/-300
+ * from world space into camera space. The transformation
+ * moves and rotates the point so it is relative to the
+ * camera, scales it according to the FOV and aspect
+ * parameters, and also flips up and front direction -
+ * ready to project the point to the viewport.
+ */
+ apply_matrix_f (&m, 100, 200, -300, &x, &y, &z);
+
+ /* Finally, the point is projected from
+ * camera space to the screen.
+ */
+ persp_project_f (cx, cy, cz, &sx, &sy);
+
+
+For more details, look at the function descriptions of
+set_projection_viewport(), get_camera_matrix(), and persp_project(), as well
+as the relevant example programs.
+
+
+All the 3d math functions are available in two versions: one which uses
+fixed point arithmetic, and another which uses floating point. The syntax
+for these is identical, but the floating point functions and structures are
+postfixed with '_f', eg. the fixed point function cross_product() has a
+floating point equivalent cross_product_f(). If you are programming in C++,
+Allegro also overloads these functions for use with the 'fix' class.
+
+
+3d transformations are accomplished by the use of a modelling matrix. This
+is a 4x4 array of numbers that can be multiplied with a 3d point to produce
+a different 3d point. By putting the right values into the matrix, it can be
+made to do various operations like translation, rotation, and scaling. The
+clever bit is that you can multiply two matrices together to produce a third
+matrix, and this will have the same effect on points as applying the
+original two matrices one after the other. For example, if you have one
+matrix that rotates a point and another that shifts it sideways, you can
+combine them to produce a matrix that will do the rotation and the shift in
+a single step. You can build up extremely complex transformations in this
+way, while only ever having to multiply each point by a single matrix.
+
+
+Allegro actually cheats in the way it implements the matrix structure.
+Rotation and scaling of a 3d point can be done with a simple 3x3 matrix, but
+in order to translate it and project it onto the screen, the matrix must be
+extended to 4x4, and the point extended into 4d space by the addition of an
+extra coordinate, w=1. This is a bad thing in terms of efficiency, but
+fortunately an optimisation is possible. Given the 4x4 matrix:
+
+ ( a, b, c, d )
+ ( e, f, g, h )
+ ( i, j, k, l )
+ ( m, n, o, p )
+
+a pattern can be observed in which parts of it do what. The top left 3x3
+grid implements rotation and scaling. The three values in the top right
+column (d, h, and l) implement translation, and as long as the matrix is
+only used for affine transformations, m, n and o will always be zero and p
+will always be 1. If you don't know what affine means, read Foley & Van
+Damme: basically it covers scaling, translation, and rotation, but not
+projection. Since Allegro uses a separate function for projection, the
+matrix functions only need to support affine transformations, which means
+that there is no need to store the bottom row of the matrix. Allegro
+implicitly assumes that it contains (0,0,0,1), and optimises the matrix
+manipulation functions accordingly. Read chapter "Structures and types
+defined by Allegro" for an internal view of the MATRIX/_f structures.
+
+
+ Constructs a translation matrix, storing it in m. When applied to the
+ point (px, py, pz), this matrix will produce the point (px+x, py+y,
+ pz+z). In other words, it moves things sideways.
+
+
+
+ Constructs a scaling matrix, storing it in m. When applied to the point
+ (px, py, pz), this matrix will produce the point (px*x, py*y, pz*z). In
+ other words, it stretches or shrinks things.
+
+
+
+ Construct X axis rotation matrices, storing them in m. When applied to a
+ point, these matrices will rotate it about the X axis by the specified
+ angle (given in binary, 256 degrees to a circle format).
+
+
+
+ Construct Y axis rotation matrices, storing them in m. When applied to a
+ point, these matrices will rotate it about the Y axis by the specified
+ angle (given in binary, 256 degrees to a circle format).
+
+
+
+ Construct Z axis rotation matrices, storing them in m. When applied to a
+ point, these matrices will rotate it about the Z axis by the specified
+ angle (given in binary, 256 degrees to a circle format).
+
+
+
+ Constructs a transformation matrix which will rotate points around all
+ three axes by the specified amounts (given in binary, 256 degrees to a
+ circle format). The direction of rotation can simply be found out with
+ the right-hand rule: Point the dumb of your right hand towards the
+ origin along the axis of rotation, and the fingers will curl in the
+ positive direction of rotation. E.g. if you rotate around the y axis,
+ and look at the scene from above, a positive angle will rotate in
+ clockwise direction.
+
+
+
+ Rotates a matrix so that it is aligned along the specified coordinate
+ vectors (they need not be normalized or perpendicular, but the up and
+ front must not be equal). A front vector of 0,0,-1 and up vector of 0,1,0
+ will return the identity matrix.
+
+
+
+ Constructs a transformation matrix which will rotate points around the
+ specified x,y,z vector by the specified angle (given in binary, 256
+ degrees to a circle format).
+
+
+
+ Constructs a transformation matrix which will rotate points around all
+ three axes by the specified amounts (given in binary, 256 degrees to a
+ circle format), scale the result by the specified amount (pass 1 for no
+ change of scale), and then translate to the requested x, y, z position.
+
+
+
+ Constructs a camera matrix for translating world-space objects into a
+ normalised view space, ready for the perspective projection. The x, y,
+ and z parameters specify the camera position, xfront, yfront, and zfront
+ are the 'in front' vector specifying which way the camera is facing
+ (this can be any length: normalisation is not required), and xup, yup,
+ and zup are the 'up' direction vector.
+
+
+ The fov parameter specifies the field of view (ie. width of the camera
+ focus) in binary, 256 degrees to the circle format. For typical
+ projections, a field of view in the region 32-48 will work well. 64
+ (90°) applies no extra scaling - so something which is one unit away
+ from the viewer will be directly scaled to the viewport. A bigger FOV
+ moves you closer to the viewing plane, so more objects will appear. A
+ smaller FOV moves you away from the viewing plane, which means you see a
+ smaller part of the world.
+
+
+ Finally, the aspect ratio is used to scale the Y dimensions of the image
+ relative to the X axis, so you can use it to adjust the proportions of
+ the output image (set it to 1 for no scaling - but keep in mind that the
+ projection also performs scaling according to the viewport size).
+ Typically, you will pass (float)w/(float)h, where w and h are the
+ parameters you passed to set_projection_viewport.
+
+
+ Note that versions prior to 4.1.0 multiplied this aspect ratio by 4/3.
+
+
+
+ Optimised routine for translating an already generated matrix: this
+ simply adds in the translation offset, so there is no need to build two
+ temporary matrices and then multiply them together.
+
+
+
+ Optimised routine for scaling an already generated matrix: this simply
+ adds in the scale factor, so there is no need to build two temporary
+ matrices and then multiply them together.
+
+
+
+ Multiplies two matrices, storing the result in out (this may be a
+ duplicate of one of the input matrices, but it is faster when the inputs
+ and output are all different). The resulting matrix will have the same
+ effect as the combination of m1 and m2, ie. when applied to a point p, (p
+ * out) = ((p * m1) * m2). Any number of transformations can be
+ concatenated in this way. Note that matrix multiplication is not
+ commutative, ie. matrix_mul(m1, m2) != matrix_mul(m2, m1).
+
+
+
+ Calculates the cross product (x1, y1, z1) x (x2, y2, z2), storing the
+ result in (*xout, *yout, *zout). The cross product is perpendicular to
+ both of the input vectors, so it can be used to generate polygon normals.
+
+
+
+ Finds the Z component of the normal vector to the specified three
+ vertices (which must be part of a convex polygon). This is used mainly in
+ back-face culling. The back-faces of closed polyhedra are never visible
+ to the viewer, therefore they never need to be drawn. This can cull on
+ average half the polygons from a scene. If the normal is negative the
+ polygon can safely be culled. If it is zero, the polygon is perpendicular
+ to the screen.
+
+
+ However, this method of culling back-faces must only be used once the X and
+ Y coordinates have been projected into screen space using persp_project()
+ (or if an orthographic (isometric) projection is being used). Note that
+ this function will fail if the three vertices are co-linear (they lie on
+ the same line) in 3D space.
+
+
+
+ Sets the viewport used to scale the output of the persp_project()
+ function. Pass the dimensions of the screen area you want to draw onto,
+ which will typically be 0, 0, SCREEN_W, and SCREEN_H. Also don't forget
+ to pass an appropriate aspect ratio to get_camera_matrix later. The
+ width and height you specify here will determine how big your viewport
+ is in 3d space. So if an object in your 3D space is w units wide, it
+ will fill the complete screen when you run into it (i.e., if it has a
+ distance of 1.0 after the camera matrix was applied. The fov and
+ aspect-ratio parameters to get_camera_matrix also apply some scaling
+ though, so this isn't always completely true). If you pass -1/-1/2/2 as
+ parameters, no extra scaling will be performed by the projection.
+
+
+
+ Projects the 3d point (x, y, z) into 2d screen space, storing the result
+ in (*xout, *yout) and using the scaling parameters previously set by
+ calling set_projection_viewport(). This function projects from the
+ normalized viewing pyramid, which has a camera at the origin and facing
+ along the positive z axis. The x axis runs left/right, y runs up/down,
+ and z increases with depth into the screen. The camera has a 90 degree
+ field of view, ie. points on the planes x=z and -x=z will map onto the
+ left and right edges of the screen, and the planes y=z and -y=z map to
+ the top and bottom of the screen. If you want a different field of view
+ or camera location, you should transform all your objects with an
+ appropriate viewing matrix, eg. to get the effect of panning the camera
+ 10 degrees to the left, rotate all your objects 10 degrees to the right.
+
+
+
+
+
quat_slerp — Version of quat_interpolate() allowing control over the rotation.
+
quat_to_matrix — Constructs a rotation matrix from a quaternion.
+
+
+
+Quaternions are an alternate way to represent the rotation part of a
+transformation, and can be easier to manipulate than matrices. As with a
+matrix, you can encode a geometric transformations in one, concatenate
+several of them to merge multiple transformations, and apply them to a
+vector, but they can only store pure rotations. The big advantage is that
+you can accurately interpolate between two quaternions to get a part-way
+rotation, avoiding the gimbal problems of the more conventional euler angle
+interpolation.
+
+
+Quaternions only have floating point versions, without any _f suffix. Other
+than that, most of the quaternion functions correspond with a matrix
+function that performs a similar operation.
+
+
+Quaternion means 'of four parts', and that's exactly what it is. Here is the
+structure:
+
+You will have lots of fun figuring out what these numbers actually mean, but
+that is beyond the scope of this documentation. Quaternions do work -- trust
+me.
+
+
+ Construct axis rotation quaternions, storing them in q. When applied to a
+ point, these quaternions will rotate it about the relevant axis by the
+ specified angle (given in binary, 256 degrees to a circle format).
+
+
+ Constructs a quaternion that will rotate points around all three axes by
+ the specified amounts (given in binary, 256 degrees to a circle format).
+
+
+
+ Constructs a quaternion that will rotate points around the specified
+ x,y,z vector by the specified angle (given in binary, 256 degrees to a
+ circle format).
+
+
+ Constructs a quaternion from a rotation matrix. Translation is discarded
+ during the conversion. Use get_align_matrix_f() if the matrix is not
+ orthonormalized, because strange things may happen otherwise.
+
+
+ Multiplies two quaternions, storing the result in out. The resulting
+ quaternion will have the same effect as the combination of p and q, ie.
+ when applied to a point, (point * out) = ((point * p) * q). Any number of
+ rotations can be concatenated in this way. Note that quaternion
+ multiplication is not commutative, ie. quat_mul(p, q) != quat_mul(q, p).
+
+
+ Multiplies the point (x, y, z) by the quaternion q, storing the result in
+ (*xout, *yout, *zout). This is quite a bit slower than apply_matrix_f(),
+ so only use it to translate a few points. If you have many points, it is
+ much more efficient to call quat_to_matrix() and then use
+ apply_matrix_f().
+
+
+ Constructs a quaternion that represents a rotation between from and to.
+ The argument t can be anything between 0 and 1 and represents where
+ between from and to the result will be. 0 returns from, 1 returns to, and
+ 0.5 will return a rotation exactly in between. The result is copied to
+ out. This function will create the short rotation (less than 180 degrees)
+ between from and to.
+
+
+
+ The same as quat_interpolate(), but allows more control over how the
+ rotation is done. The how parameter can be any one of the values:
+
+ QUAT_SHORT - like quat_interpolate(), use shortest path
+ QUAT_LONG - rotation will be greater than 180 degrees
+ QUAT_CW - rotate clockwise when viewed from above
+ QUAT_CCW - rotate counterclockwise when viewed from above
+ QUAT_USER - the quaternions are interpolated exactly as
+ given
+
object_message — Sends a message to an object and returns the answer.
+
offer_focus — Offers the input focus to a particular object.
+
popup_dialog — do_dialog() used for popup dialogs.
+
position_dialog — Moves an array of dialog objects to the specified position.
+
set_dialog_color — Sets the colors of an array of dialog objects.
+
shutdown_dialog — Destroys a dialog player returned by init_dialog().
+
shutdown_menu — Destroys a menu player object returned by init_menu().
+
update_dialog — Low level function to update a dialog player.
+
update_menu — Low level function to update a menu player.
+
+
+
+Allegro contains an object-oriented dialog manager, which was originally
+based on the Atari GEM system (form_do(), objc_draw(), etc: old ST
+programmers will know what we are talking about :-) You can use the GUI as-is
+to knock out simple interfaces for things like the test program and grabber
+utility, or you can use it as a basis for more complicated systems of your
+own. Allegro lets you define your own object types by writing new dialog
+procedures, so you can take complete control over the visual aspects of the
+interface while still using Allegro to handle input from the mouse,
+keyboard, joystick, etc.
+
+
+A GUI dialog is stored as an array of DIALOG objects, read chapter
+"Structures and types defined by Allegro" for an internal description of the
+DIALOG structure. The array should end with an object which has the proc
+pointer set to NULL. Each object has a flags field which may contain any
+combination of the bit flags:
+
+ D_EXIT - this object should close the dialog when it is
+ clicked
+ D_SELECTED - this object is selected
+ D_GOTFOCUS - this object has got the input focus
+ D_GOTMOUSE - the mouse is currently on top of this object
+ D_HIDDEN - this object is hidden and inactive
+ D_DISABLED - this object is greyed-out and inactive
+ D_DIRTY - this object needs to be redrawn
+ D_INTERNAL - don't use this! It is for internal use by the
+ library...
+ D_USER - any powers of two above this are free for your
+ own use
+
+Each object is controlled by a dialog procedure, which is stored in the proc
+pointer. This will be called by the dialog manager whenever any action
+concerning the object is required, or you can call it directly with the
+object_message() function. The dialog procedure should follow the form:
+
+It will be passed a flag (msg) indicating what action it should perform, a
+pointer to the object concerned (d), and if msg is MSG_CHAR or MSG_XCHAR,
+the key that was pressed (c). Note that d is a pointer to a specific object,
+and not to the entire dialog.
+
+
+The dialog procedure should return one of the values:
+
+ D_O_K - normal return status
+ D_CLOSE - tells the dialog manager to close the dialog
+ D_REDRAW - tells the dialog manager to redraw the entire
+ dialog
+ D_REDRAWME - tells the dialog manager to redraw the current
+ object
+ D_WANTFOCUS - requests that the input focus be given to this
+ object
+ D_USED_CHAR - MSG_CHAR and MSG_XCHAR return this if they used
+ the key
+
+Dialog procedures may be called with any of the messages:
+
+
+MSG_START:
+ Tells the object to initialise itself. The dialog manager sends this to
+ all the objects in a dialog just before it displays the dialog.
+
+
+MSG_END:
+ Sent to all objects when closing a dialog, allowing them to perform
+ whatever cleanup operations they require.
+
+
+MSG_DRAW:
+ Tells the object to draw itself onto the screen. The mouse pointer will
+ be turned off when this message is sent, so the drawing code does not
+ need to worry about it.
+
+
+MSG_CLICK:
+ Informs the object that a mouse button has been clicked while the mouse
+ was on top of the object. Typically an object will perform its own mouse
+ tracking as long as the button is held down, and only return from this
+ message handler when it is released.
+
+
+ If you process this message, use the functions gui_mouse_*() to read the
+ state of the mouse.
+
+
+MSG_DCLICK:
+ Sent when the user double-clicks on an object. A MSG_CLICK will be sent
+ when the button is first pressed, then MSG_DCLICK if it is released and
+ pressed again within a short space of time.
+
+
+ If you process this message, use the functions gui_mouse_*() to read the
+ state of the mouse.
+
+
+MSG_KEY:
+ Sent when the keyboard shortcut for the object is pressed, or if enter,
+ space, or a joystick button is pressed while it has the input focus.
+
+
+MSG_CHAR:
+ When a key is pressed, this message is sent to the object that has the
+ input focus, with a readkey() format character code (ASCII value in the
+ low byte, scancode in the high byte) as the c parameter. If the object
+ deals with the keypress it should return D_USED_CHAR, otherwise it should
+ return D_O_K to allow the default keyboard interface to operate. If you
+ need to access Unicode character input, you should use MSG_UCHAR instead
+ of MSG_CHAR.
+
+
+MSG_UCHAR:
+ If an object ignores the MSG_CHAR input, this message will be sent
+ immediately after it, passed the full Unicode key value as the c
+ parameter. This enables you to read character codes greater than 255, but
+ cannot tell you anything about the scancode: if you need to know that,
+ use MSG_CHAR instead. This handler should return D_USED_CHAR if it
+ processed the input, or D_O_K otherwise.
+
+
+MSG_XCHAR:
+ When a key is pressed, Allegro will send a MSG_CHAR and MSG_UCHAR to the
+ object with the input focus. If this object doesn't process the key (ie.
+ it returns D_O_K rather than D_USED_CHAR), the dialog manager will look
+ for an object with a matching keyboard shortcut in the key field, and
+ send it a MSG_KEY. If this fails, it broadcasts a MSG_XCHAR to all
+ objects in the dialog, allowing them to respond to special keypresses
+ even when they don't have the input focus. Normally you should ignore
+ this message (return D_O_K rather than D_USED_CHAR), in which case
+ Allegro will perform default actions such as moving the focus in response
+ to the arrow keys and closing the dialog if ESC is pressed.
+
+
+MSG_WANTFOCUS:
+ Queries whether an object is willing to accept the input focus. It should
+ return D_WANTFOCUS if it does, or D_O_K if it isn't interested in getting
+ user input.
+
+
+MSG_GOTFOCUS:
+MSG_LOSTFOCUS:
+ Sent whenever an object gains or loses the input focus. These messages
+ will always be followed by a MSG_DRAW, to let objects display themselves
+ differently when they have the input focus. If you return D_WANTFOCUS in
+ response to a MSG_LOSTFOCUS event, this will prevent your object from
+ losing the focus when the mouse moves off it onto the screen background
+ or some inert object, so it will only lose the input focus when some
+ other object is ready to take over the focus (this trick is used by the
+ d_edit_proc() object).
+
+
+MSG_GOTMOUSE:
+MSG_LOSTMOUSE:
+ Sent when the mouse moves on top of or away from an object. Unlike the
+ focus messages, these are not followed by a MSG_DRAW, so if the object is
+ displayed differently when the mouse is on top of it, it is responsible
+ for redrawing itself in response to these messages.
+
+
+MSG_IDLE:
+ Sent whenever the dialog manager has nothing better to do.
+
+
+MSG_RADIO:
+ Sent by radio button objects to deselect other buttons in the same group
+ when they are clicked. The group number is passed in the c message
+ parameter.
+
+
+MSG_WHEEL:
+ Sent to the focused object whenever the mouse wheel moves. The c message
+ parameter contains the number of clicks.
+
+
+MSG_LPRESS, MSG_MPRESS, MSG_RPRESS:
+ Sent when the corresponding mouse button is pressed.
+
+
+MSG_LRELEASE, MSG_MRELEASE, MSG_RRELEASE:
+ Sent when the corresponding mouse button is released.
+
+
+MSG_USER:
+ The first free message value. Any numbers from here on (MSG_USER,
+ MSG_USER+1, MSG_USER+2, ... MSG_USER+n) are free to use for whatever you
+ like.
+
+
+Allegro provides several standard dialog procedures. You can use these as
+they are to provide simple user interface objects, or you can call them from
+within your own dialog procedures, resulting in a kind of OOP inheritance.
+For instance, you could make an object which calls d_button_proc to draw
+itself, but handles the click message in a different way, or an object which
+calls d_button_proc for everything except drawing itself, so it would behave
+like a normal button but could look completely different.
+
+
+Since the release of Allegro version 3.9.33 (CVS), some GUI objects and
+menus are being drawn differently unlike in previous Allegro versions. The
+changes are the following:
+
+ Shadows under d_shadow_box_proc and d_button_proc are always black.
+
+ The most important (and immediately visible) change is, that some objects
+ are being drawn smaller. The difference is exactly one pixel in both
+ height and width, when comparing to previous versions. The reason is,
+ that in previous versions these objects were too large on the screen -
+ their size was d->w+1 and d->h+1 pixels (and not d->w and d->h, as it
+ should be). This change affects the following objects :
+
+ When you want to convert old dialogs to look equally when compiling with
+ the new Allegro version, just increase the size of the mentioned objects
+ by one pixel in both width and height fields.
+
+ When a GUI menu item (not in a bar menu) has a child menu, there is a
+ small arrow next to the child menu name, pointing to the right - so the
+ user can immediately see that this menu item has a child menu - and
+ there is no need to use such menu item names as for example "New...",
+ to show that it has a child menu. The submenu will be drawn to the right
+ of the parent menu, trying not to overlap it.
+
+
+
+Menus had been forgotten during the changes for 3.9.33 (CVS), so they were
+still drawn too large until version 4.1.0.
+
+
+ These draw text onto the screen. The dp field should point to the string
+ to display. d_ctext_proc() centers the string horizontally, and
+ d_rtext_proc() right aligns it. Any '&' characters in the string will
+ be replaced with lines underneath the following character, for displaying
+ keyboard shortcuts (as in MS Windows). To display a single ampersand, put
+ "&&". To draw the text in something other than the default font, set the
+ dp2 field to point to your custom font data.
+
+
+
+ A button object (the dp field points to the text string). This object can
+ be selected by clicking on it with the mouse or by pressing its keyboard
+ shortcut. If the D_EXIT flag is set, selecting it will close the dialog,
+ otherwise it will toggle on and off. Like d_text_proc(), ampersands can
+ be used to display the keyboard shortcut of the button.
+
+
+
+ This is an example of how you can derive objects from other objects. Most
+ of the functionality comes from d_button_proc(), but it displays itself
+ as a check box. If the d1 field is non-zero, the text will be printed to
+ the right of the check, otherwise it will be on the left.
+
+
+ Note: the object width should allow space for the text as well as the
+ check box (which is square, with sides equal to the object height).
+
+
+
+ A radio button object. A dialog can contain any number of radio button
+ groups: selecting a radio button causes other buttons within the same
+ group to be deselected. The dp field points to the text string, d1
+ specifies the group number, and d2 is the button style (0=circle,
+ 1=square).
+
+
+
+ A bitmap button. The fg color is used for the dotted line showing focus,
+ and the bg color for the shadow used to fill in the top and left sides of
+ the button when "pressed". d1 is the "push depth", ie. the number of
+ pixels the icon will be shifted to the right and down when selected
+ (default 2) if there is no "selected" image. d2 is the distance by which
+ the dotted line showing focus is indented (default 2). dp points to a
+ bitmap for the icon, while dp2 and dp3 are the selected and disabled
+ images respectively (optional, may be NULL).
+
+
+
+ This is an invisible object for implementing keyboard shortcuts. You can
+ put an ASCII code in the key field of the dialog object (a character such
+ as 'a' to respond to a simple keypress, or a number 1-26 to respond to a
+ control key a-z), or you can put a keyboard scancode in the d1 and/or d2
+ fields. When one of these keys is pressed, the object will call the
+ function pointed to by dp. This should return an int, which will be
+ passed back to the dialog manager, so it can return D_O_K, D_REDRAW,
+ D_CLOSE, etc.
+
+
+
+ An editable text object (the dp field points to the string). When it has
+ the input focus (obtained by clicking on it with the mouse), text can be
+ typed into this object. The d1 field specifies the maximum number of
+ characters that it will accept, and d2 is the text cursor position within
+ the string.
+
+
+ Note: dp must point to a buffer at least (d1 + 1) * 4 bytes long because,
+ depending on the encoding format in use, a single character can occupy
+ up to 4 bytes and room must be reserved for the terminating null character.
+
+
+
+ A list box object. This will allow the user to scroll through a list of
+ items and to select one by clicking or with the arrow keys. If the D_EXIT
+ flag is set, double clicking on a list item will close the dialog. The
+ index of the selected item is held in the d1 field, and d2 is used to
+ store how far it has scrolled through the list. The dp field points to a
+ function which will be called to obtain information about the contents of
+ the list. This should follow the form:
+
+ char *foobar(int index, int *list_size);
+
+ If index is zero or positive, the function should return a pointer to the
+ string which is to be displayed at position index in the list. If index
+ is negative, it should return NULL and list_size should be set to the
+ number of items in the list.
+
+
+ To create a multiple selection listbox, set the dp2 field to an array of
+ byte flags indicating the selection state of each list item (non-zero for
+ selected entries). This table must be at least as big as the number of
+ objects in the list!
+
+
+
+ Like d_list_proc, but allows the user to type in the first few characters
+ of a listbox entry in order to select it. Uses dp3 internally, so you
+ mustn't store anything important there yourself.
+
+
+
+ A text box object. The dp field points to the text which is to be
+ displayed in the box. If the text is long, there will be a vertical
+ scrollbar on the right hand side of the object which can be used to
+ scroll through the text. The default is to print the text with word
+ wrapping, but if the D_SELECTED flag is set, the text will be printed
+ with character wrapping. The d1 field is used internally to store the
+ number of lines of text, and d2 is used to store how far it has scrolled
+ through the text.
+
+
+
+ A slider control object. This object holds a value in d2, in the range
+ from 0 to d1. It will display as a vertical slider if h is greater than
+ or equal to w, otherwise it will display as a horizontal slider. The dp
+ field can contain an optional bitmap to use for the slider handle, and
+ dp2 can contain an optional callback function, which is called each time
+ d2 changes. The callback function should have the following prototype:
+
+ int function(void *dp3, int d2);
+
+ The d_slider_proc object will return the value of the callback function.
+
+
+
+ This object is a menu bar which will drop down child menus when it is
+ clicked or if an alt+key corresponding to one of the shortcuts in the
+ menu is pressed. It ignores a lot of the fields in the dialog structure,
+ in particular the color is taken from the gui_*_color variables, and the
+ width and height are calculated automatically (the w and h fields from
+ the DIALOG are only used as a minimum size.) The dp field points to an
+ array of menu structures: see do_menu() for more information. The top
+ level menu will be displayed as a horizontal bar, but when child menus
+ drop down from it they will be in the normal vertical format used by
+ do_menu(). When a menu item is selected, the return value from the menu
+ callback function is passed back to the dialog manager, so your callbacks
+ should return D_O_K, D_REDRAW, or D_CLOSE.
+
+
+
+ An invisible helper object that yields timeslices for the scheduler (if
+ the system supports it) when the GUI has nothing to do but waiting for
+ user actions. You should put one instance of this object in each dialog
+ array because it may be needed on systems with an unusual scheduling
+ algorithm (for instance QNX) in order to make the GUI fully responsive.
+
+
+
+ Hook functions, used by the GUI routines whenever they need to access the
+ mouse state. By default these just return copies of the mouse_x, mouse_y,
+ mouse_z, and mouse_b variables, but they could be used to offset or scale
+ the mouse position, or read input from a different source entirely.
+
+
+You can change the global 'font' pointer to make the GUI objects use
+something other than the standard 8x8 font. The standard dialog procedures,
+menus, and alert boxes, will work with fonts of any size, but the
+gfx_mode_select() dialog will look wrong with anything other than 8x8 fonts.
+
+
+ Helper function for use by the GUI routines. Draws a text string onto the
+ screen, interpreting the '&' character as an underbar for displaying
+ keyboard shortcuts. Returns the width of the output string in pixels.
+
+
+
+ This function can be used to change the bitmap surface the GUI routines
+ draw to. This can be useful if you are using a double buffering or page
+ flipping system. Passing NULL will cause the default surface (screen) to
+ be used again. Example:
+
+ This function returns the current bitmap surface the GUI routines will
+ use for drawing. Note that this function will return screen if you have
+ called gui_set_screen(NULL) previously, and will never return NULL.
+
+
+
+ Searches the dialog for the object which has the input focus, returning
+ an index or -1 if the focus is not set. This is useful if you are calling
+ do_dialog() several times in a row and want to leave the focus in the
+ same place it was when the dialog was last displayed, as you can call
+ do_dialog(dlg, find_dialog_focus(dlg));
+
+
+
int offer_focus(DIALOG *dialog, int obj, int *focus_obj, int force);
+ Offers the input focus to a particular object. Normally the function sends
+ the MSG_WANTFOCUS message to query whether the object is willing to accept
+ the focus. However, passing any non-zero value as force argument instructs
+ the function to authoritatively set the focus to the object.
+
+
+
+ Sends a message to an object and returns the answer it has generated.
+ Remember that the first parameter is the dialog object (not a whole
+ array) that you wish to send the message to. For example, to make the
+ second object in a dialog draw itself, you might write:
+
+ Sends a message to all the objects in an array. If any of the dialog
+ procedures return values other than D_O_K, it returns the value and sets
+ obj to the index of the object which produced it.
+
+
+
+ Broadcasts a message to all the objects in the active dialog. If any of
+ the dialog procedures return values other than D_O_K, it returns that
+ value.
+
+
+
+ The basic dialog manager function. This displays a dialog (an array of
+ dialog objects, terminated by one with a NULL dialog procedure), and sets
+ the input focus to the focus_obj (-1 if you don't want anything to have
+ the focus). It interprets user input and dispatches messages as they are
+ required, until one of the dialog procedures tells it to close the
+ dialog, at which point it returns the index of the object that caused it
+ to exit, or until ESC is pressed, at which point it returns -1.
+
+
+
+ Like do_dialog(), but it stores the data on the screen before drawing the
+ dialog and restores it when the dialog is closed. The screen area to be
+ stored is calculated from the dimensions of the first object in the
+ dialog, so all the other objects should lie within this one.
+
+
+
+ This function provides lower level access to the same functionality as
+ do_dialog(), but allows you to combine a dialog box with your own program
+ control structures. It initialises a dialog, returning a pointer to a
+ player object that can be used with update_dialog() and
+ shutdown_dialog(). With these functions, you could implement your own
+ version of do_dialog() with the lines:
+
+ Note that you are responsible for showing and hiding the mouse cursor, which
+ do_dialog would otherwise do for you, or saving and restoring the screen
+ contents, as popup_dialog would do for you.
+
+
+
+ Updates the status of a dialog object returned by init_dialog(). Returns
+ TRUE if the dialog is still active, or FALSE if it has terminated. Upon a
+ return value of FALSE, it is up to you whether to call shutdown_dialog()
+ or to continue execution. The object that requested the exit can be
+ determined from the player->obj field.
+
+
+
+ Destroys a dialog player object returned by init_dialog(), returning the
+ object that caused it to exit (this is the same as the return value from
+ do_dialog()).
+
+
+
+Popup or pulldown menus are created as an array of MENU structures. Read
+chapter "Structures and types defined by Allegro" for an internal description
+of the MENU structure.
+
+
+Each menu item contains a text string. This can use the '&' character to
+indicate keyboard shortcuts, or can be an zero-length string to display the
+item as a non-selectable splitter bar. If the string contains a "\t" tab
+character, any text after this will be right-justified, eg. for displaying
+keyboard shortcut information. The proc pointer is a function which will be
+called when the menu item is selected, and child points to another menu,
+allowing you to create nested menus. Both proc and child may be NULL. The
+proc function returns an integer which is ignored if the menu was brought up
+by calling do_menu(), but which is passed back to the dialog manager if it
+was created by a d_menu_proc() object. The array of menu items is terminated
+by an entry with a NULL text pointer.
+
+
+Menu items can be disabled (greyed-out) by setting the D_DISABLED bit in the
+flags field, and a check mark can be displayed next to them by setting the
+D_SELECTED bit. With the default alignment and font this will usually
+overlap the menu text, so if you are going to use checked menu items it
+would be a good idea to prefix all your options with a space or two, to
+ensure there is room for the check.
+
+
+
+ Displays and animates a popup menu at the specified screen coordinates
+ (these will be adjusted if the menu does not entirely fit on the screen).
+ Returns the index of the menu item that was selected, or -1 if the menu
+ was cancelled. Note that the return value cannot indicate selection from
+ child menus, so you will have to use the callback functions if you want
+ multi-level menus.
+
+
+
+ This function provides lower level access to the same functionality as
+ do_menu(), but allows you to combine a popup menu with your own program
+ control structures. It initialises a menu, returning a pointer to a menu
+ player object that can be used with update_menu() and shutdown_menu().
+ With these functions, you could implement your own version of do_menu()
+ with the lines:
+
+ Updates the status of a menu object returned by init_menu(). Returns TRUE
+ if the menu is still active, or FALSE if it has terminated. Upon a return
+ value of FALSE, it is up to you to call shutdown_menu() or to continue
+ execution.
+
+
+
+ Destroys a menu player object returned by init_menu(), returning the index
+ of the menu item that was selected, or -1 if the menu was cancelled (this
+ is the same as the return value from do_menu()).
+
+
+
+ When a menu callback procedure is triggered, this will be set to the menu
+ item that was selected, so your routine can determine where it was called
+ from.
+
+
+
+ If set, these functions will be called whenever a menu needs to be
+ drawn, so you can change how menus look.
+
+
+ gui_menu_draw_menu() is passed the position and size of the
+ menu. It should draw the background of the menu onto screen.
+
+
+ gui_menu_draw_menu_item() is called once for each menu item that is
+ to be drawn. bar will be set if the item is part of a top-level
+ horizontal menu bar, and sel will be set if the menu item is
+ selected. It should also draw onto screen.
+
+
+
int alert(const char *s1, *s2, *s3, const char *b1, *b2, int c1, c2);
+ Displays a popup alert box, containing three lines of text (s1-s3), and
+ with either one or two buttons. The text for these buttons is passed in
+ `b1' and `b2' (`b2' may be NULL), and the keyboard shortcuts in `c1' and
+ `c2' as ASCII value. Example:
+
Return value:
+ Returns 1 or 2 depending on which button was clicked. If the alert is
+ dismissed by pressing ESC when ESC is not one of the keyboard shortcuts,
+ it treats it as a click on the second button (this is consistent with the
+ common "Ok", "Cancel" alert).
+
+
+
int file_select_ex(const char *message, char *path, const char *ext,
+ int size, int w, int h);
+ Displays the Allegro file selector, with the message as caption. The path
+ parameter contains the initial filename to display (this can be used to
+ set the starting directory, or to provide a default filename for a
+ save-as operation). The user selection is returned by altering the path
+ buffer, whose maximum capacity in bytes is specified by the size parameter.
+ Note that it should have room for at least 80 characters (not bytes),
+ so you should reserve 6x that amount, just to be sure. The list of files
+ is filtered according to the file extensions in the ext parameter.
+ Passing NULL includes all files; "PCX;BMP" includes only files with
+ .PCX or .BMP extensions. If you wish to control files by their attributes,
+ one of the fields in the extension list can begin with a slash, followed
+ by a set of attribute characters. Any attribute written on its own, or
+ with a '+' before it, indicates to include only files which have that
+ attribute set. Any attribute with a '-' before it indicates to leave out
+ any files with that attribute. The flag characters are 'r' (read-only),
+ 'h' (hidden), 's' (system), 'd' (directory) and 'a' (archive). For
+ example, an extension string of "PCX;BMP;/+r-h" will display only PCX or
+ BMP files that are read-only and not hidden. The directories are not
+ affected in the same way as the other files by the extension string: the
+ extensions are never taken into account for them and the other attributes
+ are taken into account only when 'd' is mentioned in the string; in other
+ words, all directories are included when 'd' is not mentioned in the
+ string. The file selector is stretched to the width and height specified
+ in the w and h parameters, and to the size of the standard Allegro font.
+ If either the width or height argument is set to zero, it is stretched
+ to the corresponding screen dimension. This function returns zero if it
+ was closed with the Cancel button or non-zero if it was OK'd.
+
+
+
+ Displays the Allegro graphics mode selection dialog, which allows the
+ user to select a screen mode and graphics card. Stores the selection in
+ the three variables, and returns zero if it was closed with the Cancel
+ button or non-zero if it was OK'd.
+
+
+ The initial values of card, w, h are not used.
+
+
+
+ Extended version of the graphics mode selection dialog, which allows the
+ user to select the color depth as well as the resolution and hardware
+ driver.
+
+
+ This version of the function reads the initial values from the
+ parameters when it activates so you can specify the default values.
+ In fact, you should be sure not to pass in uninitialised values.
+
+
+
int gfx_mode_select_filter(int *card, int *w, int *h, int *color_depth,
+ int (*filter)(int, int, int, int));
+ Even more extended version of the graphics mode selection dialog, which
+ allows the programmer to customize the contents of the dialog and the user
+ to select the color depth as well as the resolution and hardware driver.
+ `filter' will be passed (card, w, h, color_depth) quadruplets and must
+ return 0 to let the specified quadruplet be added to the list of displayed
+ modes.
+
+
+ This version of the function reads the initial values from the
+ parameters when it activates so you can specify the default values.
+ In fact, you should be sure not to pass in uninitialised values.
+
+
+
+ If set, these functions will be used by the standard Allegro dialogs.
+ This allows you to customise the look and feel, much like gui_fg_color
+ and gui_bg_color, but much more flexibly.
+
+
+
+
+
+There are four Allegro files which you should redistribute along your program.
+These are the files `keyboard.dat', `language.dat', `allegro.cfg' and
+`setup.exe'.
+
+
+The first two contain internationalisation information for keyboard mappings
+and system messages to show up localised on the user's computer. The
+`setup.exe' program, which comes in Allegro's `setup' directory, is a
+standalone tool which you can graphically customise and even embed into your
+main binary. The user can generate a configuration file with this tool, to
+store special settings or avoid Allegro's autodetection failing on specific
+hardware. Even if you distribute `setup.exe', you are recommended to copy too
+the empty `allegro.cfg' file, in case the setup program itself is unable to
+run and the user has to edit manually the configuration with a text editor.
+
+
+If you are using get_config_text() in your program to localise text strings,
+merge your xxtext.cfg files with the ones provided by Allegro in the
+`resource' directory before creating `language.dat', and redistribute this
+with your program. This file will contain then both Allegro's system
+messages and the strings of your program.
+
+
+ The DOS library supports the following type parameters for the
+ install_joystick() function:
+
+ JOY_TYPE_AUTODETECT
+ Attempts to autodetect your joystick hardware. It isn't possible to
+ reliably distinguish between all the possible input setups, so this
+ routine can only ever choose the standard joystick, Sidewider, GamePad
+ Pro, or GrIP drivers, but it will use information from the
+ configuration file if one is available (this can be created using the
+ setup utility or by calling the save_joystick_data() function), so you
+ can always use JOY_TYPE_AUTODETECT in your code and then select the
+ exact hardware type from the setup program.
+
+ JOY_TYPE_NONE
+ Dummy driver for machines without any joystick.
+
+ JOY_TYPE_STANDARD
+ A normal two button stick.
+
+ JOY_TYPE_2PADS
+ Dual joystick mode (two sticks, each with two buttons).
+
+ JOY_TYPE_4BUTTON
+ Enable the extra buttons on a 4-button joystick.
+
+ JOY_TYPE_6BUTTON
+ Enable the extra buttons on a 6-button joystick.
+
+ JOY_TYPE_8BUTTON
+ Enable the extra buttons on an 8-button joystick.
+
+ JOY_TYPE_FSPRO
+ CH Flightstick Pro or compatible stick, which provides four buttons,
+ an analogue throttle control, and a 4-direction coolie hat.
+
+ JOY_TYPE_WINGEX
+ A Logitech Wingman Extreme, which should also work with any
+ Thrustmaster Mk.I compatible joystick. It provides support for four
+ buttons and a coolie hat. This also works with the Wingman Warrior, if
+ you plug in the 15 pin plug (remember to unplug the 9-pin plug!) and
+ set the tiny switch in front to the "H" position (you will not be able
+ to use the throttle or the spinner though).
+
+ JOY_TYPE_SIDEWINDER
+ The Microsoft Sidewinder digital pad (supports up to four controllers,
+ each with ten buttons and a digital direction control).
+
+ JOY_TYPE_SIDEWINDER_AG
+ An alternative driver to JOY_TYPE_SIDEWINDER.
+ Try this if your Sidewinder isn't recognized with JOY_TYPE_SIDEWINDER.
+
+ JOY_TYPE_SIDEWINDER_PP
+ The Microsoft Sidewinder 3D/Precision/Force Feedback Pro joysticks.
+
+ JOY_TYPE_GAMEPAD_PRO
+ The Gravis GamePad Pro (supports up to two controllers, each with ten
+ buttons and a digital direction control).
+
+ JOY_TYPE_GRIP
+ Gravis GrIP driver, using the grip.gll driver file.
+
+ JOY_TYPE_GRIP4
+ Version of the Gravis GrIP driver that is constrained to only move
+ along the four main axes.
+
+ JOY_TYPE_SNESPAD_LPT1
+ JOY_TYPE_SNESPAD_LPT2
+ JOY_TYPE_SNESPAD_LPT3
+ SNES joypads connected to LPT1, LPT2, and LPT3 respectively.
+
+ JOY_TYPE_PSXPAD_LPT1
+ JOY_TYPE_PSXPAD_LPT2
+ JOY_TYPE_PSXPAD_LPT3
+ PSX joypads connected to LPT1, LPT2, and LPT3 respectively. See
+ http://www.ziplabel.com/dpadpro/index.html for information
+ about the parallel cable required. The driver automagically detects
+ which types of PSX pads are connected out of digital, analog (red or
+ green mode), NegCon, multi taps, Namco light guns, Jogcons (force
+ feedback steering wheel) and the mouse. If the controller isn't
+ recognised it is treated as an analog controller, meaning the driver
+ should work with just about anything. You can connect controllers in
+ any way you see fit, but only the first 8 will be used.
+
+ The Sony Dual Shock or Namco Jogcon will reset themselves (to digital
+ mode) after not being polled for 5 seconds. This is normal, the same
+ thing happens on a Playstation, it's designed to stop any vibration in
+ case the host machine crashes. Other mode switching controllers may
+ have similar quirks. However, if this happens to a Jogcon controller
+ the mode button is disabled. To reenable the mode button on the Jogcon
+ you need to hold down the Start and Select buttons at the same time.
+
+ The G-con45 needs to be connected to (and pointed at) a TV type monitor
+ connected to your computer. The composite video out on my video card
+ works fine for this (a Hercules Stingray 128/3D 8Mb). The TV video
+ modes in Mame should work too.
+
+ JOY_TYPE_N64PAD_LPT1
+ JOY_TYPE_N64PAD_LPT2
+ JOY_TYPE_N64PAD_LPT3
+ N64 joypads connected to LPT1, LPT2, and LPT3 respectively. See
+ http://www.st-hans.de/N64.htm for information about the
+ necessary hardware adaptor. It supports up to four controllers on a
+ single parallel port. There is no need to calibrate the analog stick,
+ as this is done by the controller itself when powered up. This means
+ that the stick has to be centred when the controller is initialised.
+ One possible issue people may have with this driver is that it is
+ physically impossible to move the analog stick fully diagonal, but I
+ can't see this causing any major problems. This is because of the
+ shape of the rim that the analog stick rests against. Like the Gravis
+ Game Pad Pro, this driver briefly needs to disable hardware interrupts
+ while polling. This causes a noticable performance hit on my machine
+ in both drivers, but there is no way around it. At a (very) rough
+ guess I'd say it slows down Mame 5% - 10%.
+
+ JOY_TYPE_DB9_LPT1
+ JOY_TYPE_DB9_LPT2
+ JOY_TYPE_DB9_LPT3
+ A pair of two-button joysticks connected to LPT1, LPT2, and LPT3
+ respectively. Port 1 is compatible with Linux joy-db9 driver
+ (multisystem 2-button), and port 2 is compatible with Atari interface
+ for DirectPad Pro. See the source file (src/dos/multijoy.c) for pinout
+ information.
+
+ JOY_TYPE_TURBOGRAFIX_LPT1
+ JOY_TYPE_TURBOGRAFIX_LPT2
+ JOY_TYPE_TURBOGRAFIX_LPT3
+ These drivers support up to 7 joysticks, each one with up to 5
+ buttons, connected to LPT1, LPT2, and LPT3 respectively. They use the
+ TurboGraFX interface by Steffen Schwenke: see
+ http://www.burg-halle.de/~schwenke/parport.html for details
+ on how to build this.
+
+ JOY_TYPE_WINGWARRIOR
+ A Wingman Warrior joystick.
+
+ JOY_TYPE_IFSEGA_ISA
+ JOY_TYPE_IFSEGA_PCI
+ JOY_TYPE_IFSEGA_PCI_FAST
+ Drivers for the IF-SEGA joystick interface cards by the IO-DATA
+ company (these come in PCI, PCI2, and ISA variants).
+
+ The DOS library supports the following card parameters for the
+ set_gfx_mode() function:
+
+ GFX_TEXT
+ Return to text mode.
+
+ GFX_AUTODETECT
+ Let Allegro pick an appropriate graphics driver.
+
+ GFX_AUTODETECT_FULLSCREEN
+ Autodetects a graphics driver, but will only use fullscreen drivers,
+ failing if these are not available on current platform.
+
+ GFX_AUTODETECT_WINDOWED
+ Same as above, but uses only windowed drivers. This will always fail
+ under DOS.
+
+ GFX_SAFE
+ Special driver for when you want to reliably set a graphics mode and
+ don't really care what resolution or color depth you get. See the
+ set_gfx_mode() documentation for details.
+
+ GFX_VGA
+ The standard 256-color VGA mode 13h, using the GFX_VGA driver. This is
+ normally sized 320x200, which will work on any VGA but doesn't support
+ large virtual screens and hardware scrolling. Allegro also provides
+ some tweaked variants of the mode which are able to scroll, sized
+ 320x100 (with a 200 pixel high virtual screen), 160x120 (with a 409
+ pixel high virtual screen), 256x256 (no scrolling), and 80x80 (with a
+ 819 pixel high virtual screen).
+
+ GFX_MODEX
+ Mode-X will work on any VGA card, and provides a range of different
+ 256-color tweaked resolutions.
+
+ These only work on some monitors. They were fine on my old machine,
+ but don't get on very well with my new monitor. If you are worried
+ about the possibility of damaging your monitor by using these
+ modes, don't be. Of course I'm not providing any warranty with any
+ of this, and if your hardware does blow up that is tough, but I
+ don't think this sort of tweaking can do any damage. From the
+ documentation of Robert Schmidt's TWEAK program:
+
+ "Some time ago, putting illegal or unsupported values or
+ combinations of such into the video card registers might prove
+ hazardous to both your monitor and your health. I have *never*
+ claimed that bad things can't happen if you use TWEAK, although
+ I'm pretty sure it never will. I've never heard of any damage
+ arising from trying out TWEAK, or from general VGA tweaking in
+ any case."
+
+ Most of the mode-X drawing functions are slower than in mode 13h, due
+ to the complexity of the planar bitmap organisation, but solid area
+ fills and plane-aligned blits from one part of video memory to another
+ can be significantly faster, particularly on older hardware. Mode-X
+ can address the full 256k of VGA RAM, so hardware scrolling and page
+ flipping are possible, and it is possible to split the screen in order
+ to scroll the top part of the display but have a static status
+ indicator at the bottom.
+
+ GFX_VESA1
+ Use the VESA 1.x driver.
+
+ GFX_VESA2B
+ Use the VBE 2.0 banked mode driver.
+
+ GFX_VESA2L
+ Use the VBE 2.0 linear framebuffer driver.
+
+ GFX_VESA3
+ Use the VBE 3.0 driver. This is the only VESA driver that supports the
+ request_refresh_rate() function.
+
+ The standard VESA modes are 640x480, 800x600, and 1024x768. These
+ ought to work with any SVGA card: if they don't, get a copy of the
+ SciTech Display Doctor and see if that fixes it. What color depths are
+ available will depend on your hardware. Most cards support both 15 and
+ 16-bit resolutions, but if at all possible I would advise you to
+ support both (it's not hard...) in case one is not available. Some
+ cards provide both 24 and 32-bit truecolor, in which case it is a
+ choice between 24 (saves memory) or 32 (faster), but many older cards
+ have no 32-bit mode and some newer ones don't support 24-bit
+ resolutions. Use the vesainfo test program to see what modes your VESA
+ driver provides.
+
+ Many cards also support 640x400, 1280x1024, and 1600x1200, but these
+ aren't available on everything, for example the S3 chipset has no
+ 640x400 mode. Other weird resolution may be possible, eg. some Tseng
+ boards can do 640x350, and the Avance Logic has a 512x512 mode.
+
+ The SciTech Display Doctor provides several scrollable low resolution
+ modes in a range of different color depths (320x200, 320x240, 320x400,
+ 320x480, 360x200, 360x240, 360x400, and 360x480 all work on my ET4000
+ with 8, 15, or 16 bits per pixel). These are lovely, allowing
+ scrolling and page flipping without the complexity of the mode-X
+ planar setup, but unfortunately they aren't standard so you will need
+ Display Doctor in order to use them.
+
+ GFX_VBEAF
+ VBE/AF is a superset of the VBE 2.0 standard, which provides an API
+ for accessing hardware accelerator features. VBE/AF drivers are
+ currently only available from the FreeBE/AF project or as part of the
+ SciTech Display Doctor package, but they can give dramatic speed
+ improvements when used with suitable hardware. For a detailed
+ discussion of hardware acceleration issues, refer to the documentation
+ for the gfx_capabilities flag.
+
+ You can use the afinfo test program to check whether you have a VBE/AF
+ driver, and to see what resolutions it supports.
+
+ The SciTech VBE/AF drivers require nearptr access to be enabled, so
+ any stray pointers are likely to crash your machine while their
+ drivers are in use. This means it may be a good idea to use VESA while
+ debugging your program, and only switch to VBE/AF once the code is
+ working correctly. The FreeBE/AF drivers do not have this problem.
+
+ GFX_XTENDED
+ An unchained 640x400 mode, as described by Mark Feldman in the PCGPE.
+ This uses VESA to select an SVGA mode (so it will only work on cards
+ supporting the VESA 640x400 resolution), and then unchains the VGA
+ hardware as for mode-X. This allows the entire screen to be addressed
+ without the need for bank switching, but hardware scrolling and page
+ flipping are not possible. This driver will never be autodetected (the
+ normal VESA 640x400 mode will be chosen instead), so if you want to
+ use it you will have to explicitly pass GFX_XTENDED to set_gfx_mode().
+
+ There are a few things you need to be aware of for scrolling:
+ most VESA implementations can only handle horizontal scrolling in four
+ pixel increments, so smooth horizontal panning is impossible in SVGA modes.
+ A significant number of VESA implementations seem to be very buggy when it
+ comes to scrolling in truecolor video modes, so you shouldn't depend on
+ this routine working correctly in the truecolor resolutions unless you can
+ be sure that SciTech Display Doctor is installed. Hardware scrolling may
+ also not work at all under Windows.
+
+
+ Triple buffering is only possible with certain drivers: it will work in any
+ DOS mode-X resolution if the timer retrace simulator is active (but this
+ doesn't work correctly under Windows 95), plus it is supported by the
+ VBE 3.0 and VBE/AF drivers for a limited number graphics cards.
+
+
+ When running in clean DOS mode, the timer handler dynamically reprograms
+ the clock chip to generate interrupts at exactly the right times, which
+ gives an extremely high accuracy. Unfortunately, this constant speed
+ adjustment doesn't work under most multitasking systems (notably
+ Windows), so there is an alternative mode that just locks the hardware
+ timer interrupt to a speed of 200 ticks per second. This reduces the
+ accuracy of the timer (for instance, rest() will round the delay time to
+ the nearest 5 milliseconds), and prevents the vertical retrace simulator
+ from working, but on the plus side, it makes Allegro programs work under
+ Windows. This flag is set by allegro_init() if it detects the presence of
+ a multitasking OS, and enables the fixed rate timer mode.
+
+
+
+
+
MIDI_*/Windows — Supported Windows MIDI sound drivers.
+
set_gdi_color_format — Tells Allegro to use the GDI color layout for truecolor images.
+
set_palette_to_hdc — Selects and realizes a palette on the specified device context.
+
stretch_blit_from_hdc — Blits from a Windows device context to an Allegro memory bitmap.
+
stretch_blit_to_hdc — Blits an Allegro memory bitmap to a Windows device context.
+
win_get_dc — Retrieves a handle to the device context.
+
win_get_window — Retrieves a handle to the window used by Allegro.
+
win_release_dc — Releases a handle to the device context.
+
win_set_window — Registers an user-created window to be used by Allegro.
+
win_set_wnd_create_proc — Registers a custom procedure to be used by Allegro for creating its window.
+
+
+
+In terms of file redistribution, the Windows platform behaves practically the
+same as the DOS platform. Read section chapter "Dos specifics" in the manual
+to learn more about this.
+
+
+A Windows program that uses the Allegro library is only required to include
+one or more header files from the include/allegro tree, or allegro.h; however,
+if it also needs to directly call non portable Win32 API functions, it must
+include the Windows-specific header file winalleg.h after the Allegro headers,
+and before any Win32 API header file. By default winalleg.h includes the main
+Win32 C API header file windows.h. If instead you want to use the C++
+interface to the Win32 API (a.k.a. the Microsoft Foundation Classes), define
+the preprocessor symbol ALLEGRO_AND_MFC before including any Allegro header
+so that afxwin.h will be included. Note that, in this latter case, the Allegro
+debugging macros ASSERT() and TRACE() are renamed AL_ASSERT() and AL_TRACE()
+respectively.
+
+
+Windows GUI applications start with a WinMain() entry point, rather than the
+standard main() entry point. Allegro is configured to build GUI applications
+by default and to do some magic in order to make a regular main() work with
+them, but you have to help it out a bit by writing END_OF_MAIN() right after
+your main() function. If you don't want to do that, you can just include
+winalleg.h and write a WinMain() function. Note that this magic may bring
+about conflicts with a few programs using direct calls to Win32 API
+functions; for these programs, the regular WinMain() is required and the
+magic must be disabled by defining the preprocessor symbol
+ALLEGRO_NO_MAGIC_MAIN before including Allegro headers.
+
+
+If you want to build a console application using Allegro, you have to define
+the preprocessor symbol ALLEGRO_USE_CONSOLE before including Allegro headers;
+it will instruct the library to use console features and also to disable the
+special processing of the main() function described above.
+
+
+When creating the main window, Allegro searches the executable for an ICON
+resource named "allegro_icon". If it is present, Allegro automatically
+loads it and uses it as its application icon; otherwise, Allegro uses the
+default IDI_APPLICATION icon. See the manual of your compiler for a method
+to create an ICON resource, or use the wfixicon utility from the tools/win
+directory.
+
+
+DirectX requires that system and video bitmaps (including the screen) be
+locked before you can draw onto them. This will be done automatically, but
+you can usually get much better performance by doing it yourself: see the
+acquire_bitmap() function for details.
+
+
+Due to a major oversight in the design of DirectX, there is no way to
+preserve the contents of video memory when the user switches away from your
+program. You need to be prepared for the fact that your screen contents, and
+the contents of any video memory bitmaps, may be destroyed at any point. You
+can use the set_display_switch_callback() function to find out when this
+happens.
+
+
+On the Windows platform, the only return values for the desktop_color_depth()
+function are 8, 16, 24 and 32. This means that 15-bit and 16-bit desktops
+cannot be differentiated and are both reported as 16-bit desktops. See
+below for the consequences for windowed and overlay DirectX drivers.
+
+
+ The Windows library supports the following type parameters for the
+ install_joystick() function:
+
+ JOY_TYPE_AUTODETECT
+ Attempts to autodetect your joystick hardware. It will use information
+ from the configuration file if one is available (this can be created
+ using the setup utility or by calling the save_joystick_data()
+ function), so you can always use JOY_TYPE_AUTODETECT in your code and
+ then select the exact hardware type from the setup program.
+
+ JOY_TYPE_NONE
+ Dummy driver for machines without any joystick.
+
+ JOY_TYPE_DIRECTX
+ Use DirectInput to access the joystick.
+
+ JOY_TYPE_WIN32
+ Use the regular Win32 interface rather than DirectInput to access the
+ joystick.
+
+ The Windows library supports the following card parameters for the
+ set_gfx_mode() function:
+
+ GFX_TEXT
+ This closes any graphics mode previously opened with set_gfx_mode.
+
+ GFX_AUTODETECT
+ Let Allegro pick an appropriate graphics driver.
+
+ GFX_AUTODETECT_FULLSCREEN
+ Autodetects a graphics driver, but will only use fullscreen drivers,
+ failing if these are not available on current platform.
+
+ GFX_AUTODETECT_WINDOWED
+ Same as above, but uses only windowed drivers.
+
+ GFX_SAFE
+ Special driver for when you want to reliably set a graphics mode and
+ don't really care what resolution or color depth you get. See the
+ set_gfx_mode() documentation for details.
+
+ GFX_DIRECTX
+ Alias for GFX_DIRECTX_ACCEL.
+
+ GFX_DIRECTX_ACCEL
+ The regular fullscreen DirectX driver, running with hardware
+ acceleration enabled.
+
+ GFX_DIRECTX_SOFT
+ DirectX fullscreen driver that only uses software drawing, rather than
+ any hardware accelerated features.
+
+ GFX_DIRECTX_SAFE
+ Simplified fullscreen DirectX driver that doesn't support any hardware
+ acceleration, video or system bitmaps, etc.
+
+ GFX_DIRECTX_WIN
+ The regular windowed DirectX driver, running in color conversion mode
+ when the color depth doesn't match that of the Windows desktop. Color
+ conversion is much slower than direct drawing and is not supported
+ between 15-bit and 16-bit color depths. This limitation is needed to
+ work around that of desktop_color_depth() (see above) and allows to
+ select the direct drawing mode in a reliable way on desktops reported
+ as 16-bit:
+
+ if (desktop_color_depth() == 16) {
+ set_color_depth(16);
+ if (set_gfx_mode(GFX_DIRECTX_WIN, 640, 480, 0, 0)
+ != 0) {
+ set_color_depth(15);
+ if (set_gfx_mode(GFX_DIRECTX_WIN, 640, 480, 0, 0)
+ != 0) {
+ /* 640x480 direct drawing mode not supported */
+ goto Error;
+ }
+ }
+ /* ok, we are in direct drawing mode */
+ }
+
+ Note that, mainly for performance reasons, this driver requires the
+ width of the screen to be a multiple of 4.
+ This driver is capable of displaying a hardware cursor, but there are
+ size restrictions. Typically, the cursor image cannot be more than
+ 32x32 pixels.
+
+ GFX_DIRECTX_OVL
+ The DirectX overlay driver. It uses special hardware features to run
+ your program in a windowed mode: it doesn't work on all hardware, but
+ performance is excellent on cards that are capable of it. It requires
+ the color depth to be the same as that of the Windows desktop. In light
+ of the limitation of desktop_color_depth() (see above), the reliable
+ way of setting the overlay driver on desktops reported as 16-bit is:
+
+ if (desktop_color_depth() == 16) {
+ set_color_depth(16);
+ if (set_gfx_mode(GFX_DIRECTX_OVL, 640, 480, 0, 0)
+ != 0) {
+ set_color_depth(15);
+ if (set_gfx_mode(GFX_DIRECTX_OVL, 640, 480, 0, 0)
+ != 0) {
+ /* 640x480 overlay driver not supported */
+ goto Error;
+ }
+ }
+ /* ok, the 640x480 overlay driver is running */
+ }
+
+ GFX_GDI
+ The windowed GDI driver. It is extremely slow, but is guaranteed to
+ work on all hardware, so it can be useful for situations where you
+ want to run in a window and don't care about performance. Note that
+ this driver features a hardware mouse cursor emulation in order to
+ speed up basic mouse operations (like GUI operations).
+
+ The Windows sound functions support the following digital soundcards:
+
+ DIGI_AUTODETECT - let Allegro pick a digital sound driver
+ DIGI_NONE - no digital sound
+ DIGI_DIRECTX(n) - use DirectSound device #n (zero-based)
+ with direct mixing
+ DIGI_DIRECTAMX(n) - use DirectSound device #n (zero-based)
+ with Allegro mixing
+ DIGI_WAVOUTID(n) - high (n=0) or low (n=1) quality WaveOut
+ device
+The following functions provide a platform specific interface to seamlessly
+integrate Allegro into general purpose Win32 programs. To use these routines,
+you must include winalleg.h after other Allegro headers.
+
+
+ Retrieves a handle to the window used by Allegro. Note that Allegro
+ uses an underlying window even though you don't set any graphics mode,
+ unless you have installed the neutral system driver (SYSTEM_NONE).
+
+
+ Registers an user-created window to be used by Allegro. This function is
+ meant to be called before initialising the library with allegro_init()
+ or installing the autodetected system driver (SYSTEM_AUTODETECT). It
+ lets you attach Allegro to any already existing window and prevents the
+ library from creating its own, thus leaving you total control over the
+ window; in particular, you are responsible for processing the events as
+ usual (Allegro will automatically monitor a few of them, but will not
+ filter out any of them). You can then use every component of the library
+ (graphics, mouse, keyboard, sound, timers and so on), bearing in mind
+ that some Allegro functions are blocking (e.g. readkey() if the key buffer
+ is empty) and thus must be carefully manipulated by the window thread.
+
+
+ However you can also call it after the library has been initialised,
+ provided that no graphics mode is set. In this case the keyboard, mouse,
+ joystick, sound and sound recording modules will be restarted.
+
+
+ Passing NULL instructs Allegro to switch back to its built-in window if
+ an user-created window was registered, or to request a new handle from
+ Windows for its built-in window if this was already in use.
+
+
+ Registers an user-defined procedure to be used by Allegro for creating
+ its window. This function must be called *before* initializing the
+ library with allegro_init() or installing the autodetected system
+ driver (SYSTEM_AUTODETECT). It lets you customize Allegro's window but
+ only by its creation: unlike with win_set_window(), you have no control
+ over the window once it has been created (in particular, you are not
+ responsible for processing the events). The registered function will be
+ passed a window procedure (WNDPROC object) that it must make the
+ procedure of the new window of and it must return a handle to the new
+ window. You can then use the full-featured library in the regular way.
+
+
+The following GDI routines are a very platform specific thing, to allow
+drawing Allegro memory bitmaps onto a Windows device context. When you want
+to use this, you'll have to install the neutral system driver (SYSTEM_NONE)
+or attach Allegro to an external window with win_set_window().
+
+
+There are two ways to draw your Allegro bitmaps to the Windows GDI. When you
+are using static bitmaps (for example just some pictures loaded from a
+datafile), you can convert them to DDB (device-dependent bitmaps) with
+convert_bitmap_to_hbitmap() and then just use Win32's BitBlt() to draw it.
+
+
+When you are using dynamic bitmaps (for example some things which react to
+user input), it's better to use set_palette_to_hdc() and blit_to_hdc()
+functions, which work with DIB (device-independent bitmaps).
+
+
+There are also functions to blit from a device context into an Allegro
+BITMAP, so you can do things like screen capture.
+
+
+All the drawing and conversion functions use the current palette as a color
+conversion table. You can alter the current palette with the
+set_palette_to_hdc() or select_palette() functions. Warning: when the GDI
+system color palette is explicitly changed, (by another application, for
+example) the current Allegro palette is not updated along with it!
+
+
+To use these routines, you must include winalleg.h after Allegro headers.
+
+
+ Tells Allegro to use the GDI color layout for truecolor images. This is
+ optional, but it will make the conversions work faster. If you are going
+ to call this, you should do it right after initialising Allegro and
+ before creating any graphics.
+
+
+ Converts an Allegro memory bitmap to a Windows DDB and returns a handle
+ to it. This bitmap uses its own memory, so you can destroy the original
+ bitmap without affecting the converted one. You should call
+ DeleteObject() when you no longer need this bitmap.
+
+
+
+ Blits from a Windows device context to an Allegro memory bitmap, using
+ the same parameters as the blit() function. See stretch_blit_from_hdc()
+ for details.
+
+
+
+ Blits from a Windows device context to an Allegro memory bitmap, using
+ the same parameters as the stretch_blit() function. It uses the current
+ Allegro palette and does conversion to this palette, regardless of the
+ current DC palette. So if you are blitting from 8-bit mode, you should
+ first set the DC palette with the set_palette_to_hdc() function.
+
+
+
+
+Under Unix you usually have two ways of redistributing your binaries. You
+either pack everything in a single directory, even providing Allegro in
+binary or source form for the user to compile. Or your program is being
+packaged separately from Allegro and stored in different paths. For the
+first case of redistribution, read section "Files shared by Allegro" from
+the "Dos specifics" chapter to learn more about this.
+
+
+For the second type, you can ignore redistributing the setup, keyboard
+mappings and language datafiles, because they will be already installed in
+the system. This, however, is problematic if you are using get_config_text()
+to localise your program's text strings.
+
+
+The problem is that on other platforms you usually mix your program's text
+strings with those of Allegro (found in the `resources' directory) to create
+a special language.dat. And it is likely that the Allegro library installed
+on the user's system already contains a datafile.dat. You can go ahead and
+still provide your own language.dat file, but this will mean that if Allegro
+is updated, your language.dat file may not contain all the text strings used
+by the new version.
+
+
+Given the slow paced release cycle of Allegro, this might not be a concern.
+However, if you want to make it easy on system administrators, instead of
+providing your own `language.dat', you should provide the separate
+`xxtext.cfg' files it in a separate directory. Then, before showing the
+strings to the user you can detect the language setting and use
+override_config_file() with the appropriate localisation file and call
+reload_config_texts().
+
+
+In order to locate things like the config and translation files, Allegro
+needs to know the path to your executable. Since there is no standard way to
+find that, it needs to capture a copy of your argv[] parameter, and it does
+this with some preprocessor macro trickery. Unfortunately it can't quite
+pull this off without a little bit of your help, so you will have to write
+END_OF_MAIN() right after your main() function. Pretty easy, really, and if
+you forget, you'll get a nice linker error about a missing _mangled_main
+function to remind you :-)
+
+
+Under Unix resources are searched for in many different paths (see above).
+When a configuration resource is looked for, it is usually tried with the
+variations `name.cfg' or `.namerc' in multiple paths: the current directory,
+the directory pointed to by the ALLEGRO environment variable, the user's home
+directory, one or more global system directories which usually only the
+root user has access to and any custom paths set up with
+set_allegro_resource_path(). Text files, like the main allegro config file or
+a language text translation files are looked for in the following places:
+
+Note that if you have installed Allegro from the source distribution with
+the typical `make install', global files like `language.dat' and
+`allegro.cfg' will not have been installed. As a system administrator you are
+required to install them manually wherever you prefer to have them. If you
+suspect that an Allegro program is somehow not finding the correct
+configuration file, you could try using the following command:
+
+ strace program 2>&1|egrep "(open|stat)"
+
+The strace program traces system calls and signals. By default it outputs
+the information to stderr, so that's why we redirect it to stdin with `2>&1'.
+Since we are interested only in files being (un)successfully opened, we
+restrict the output of the log to stat or open calls with the extended grep
+command. You could add another grep to filter only lines with text like
+`language' or `allegro'.
+
+
+ The Linux library supports the following type parameters for the
+ install_joystick() function:
+
+ JOY_TYPE_AUTODETECT
+ Attempts to autodetect your joystick hardware. It will use information
+ from the configuration file if one is available (this can be created
+ using the setup utility or by calling the save_joystick_data()
+ function), so you can always use JOY_TYPE_AUTODETECT in your code and
+ then select the exact hardware type from the setup program.
+
+ JOY_TYPE_NONE
+ Dummy driver for machines without any joystick.
+
+ JOY_TYPE_LINUX_ANALOGUE
+ Regular joystick interface. Joystick support needs to be enabled in your
+ kernel.
+
+ When running in Linux console mode, Allegro supports the following card
+ parameters for the set_gfx_mode() function:
+
+ GFX_TEXT
+ Return to text mode.
+
+ GFX_AUTODETECT
+ Let Allegro pick an appropriate graphics driver.
+
+ GFX_AUTODETECT_FULLSCREEN
+ Autodetects a graphics driver, but will only use fullscreen drivers,
+ failing if these are not available on current platform.
+
+ GFX_AUTODETECT_WINDOWED
+ Same as above, but uses only windowed drivers. This will always fail
+ under Linux console mode.
+
+ GFX_SAFE
+ Special driver for when you want to reliably set a graphics mode and
+ don't really care what resolution or color depth you get. See the
+ set_gfx_mode() documentation for details.
+
+ GFX_FBCON
+ Use the framebuffer device (eg. /dev/fb0). This requires you to have
+ framebuffer support compiled into your kernel, and correctly
+ configured for your hardware. It is currently the only console mode
+ driver that will work without root permissions, unless you are using
+ a development version of SVGAlib.
+
+ GFX_VBEAF
+ Use a VBE/AF driver (vbeaf.drv), assuming that you have installed one
+ which works under Linux (currently only two of the FreeBE/AF project
+ drivers are capable of this: I don't know about the SciTech ones).
+ VBE/AF requires root permissions, but is currently the only Linux
+ driver which supports hardware accelerated graphics.
+
+ GFX_SVGALIB
+ Use the SVGAlib library for graphics output. This requires root
+ permissions if your version of SVGAlib requires them.
+
+ GFX_VGA
+ GFX_MODEX
+ Use direct hardware access to set standard VGA or mode-X resolutions,
+ supporting the same modes as in the DOS versions of these drivers.
+ Requires root permissions.
+
+ When running in X mode, Allegro supports the following card parameters
+ for the set_gfx_mode() function:
+
+ GFX_TEXT
+ This closes any graphics mode previously opened with set_gfx_mode.
+
+ GFX_AUTODETECT
+ Let Allegro pick an appropriate graphics driver.
+
+ GFX_AUTODETECT_FULLSCREEN
+ Autodetects a graphics driver, but will only use fullscreen drivers,
+ failing if these are not available on current platform.
+
+ GFX_AUTODETECT_WINDOWED
+ Same as above, but uses only windowed drivers.
+
+ GFX_SAFE
+ Special driver for when you want to reliably set a graphics mode and
+ don't really care what resolution or color depth you get. See the
+ set_gfx_mode() documentation for details.
+
+ GFX_XWINDOWS
+ The standard X graphics driver. This should work on any Unix system,
+ and can operate remotely. It does not require root permissions.
+ If the ARGB cursor extension is available, this driver is capable
+ of displaying a hardware cursor. This needs to be enabled by calling
+ enable_hardware_cursor() becaue it cannot be used reliably alongside
+ get_mouse_mickeys().
+
+ GFX_XWINDOWS_FULLSCREEN
+ The same as above, but while GFX_XWINDOWS runs windowed, this one uses
+ the XF86VidMode extension to make it run in fullscreen mode even
+ without root permissions. You're still using the standard X protocol
+ though, so expect the same low performances as with the windowed
+ driver version.
+ If the ARGB cursor extension is available, this driver is capable
+ of displaying a hardware cursor. This needs to be enabled by calling
+ enable_hardware_cursor() becaue it cannot be used reliably alongside
+ get_mouse_mickeys().
+
+ GFX_XDGA2
+ Use new DGA 2.0 extension provided by XFree86 4.0.x. This will work
+ in fullscreen mode, and it will support hardware acceleration if
+ available. This driver requires root permissions.
+
+ GFX_XDGA2_SOFT
+ The same as GFX_XDGA2, but turns off hardware acceleration support.
+ This driver requires root permissions.
+
+ This function is only available under X. It lets you to specify the
+ window name and group (or class). They are important because they allow
+ the window manager to remember the window attributes (position, layer,
+ etc). Note that the name and the title of the window are two different
+ things: the title is what appears in the title bar of the window, but
+ usually has no other effects on the behaviour of the application.
+
+
+
+ This is a pointer to the Allegro X11 icon, which is in the format of
+ standard .xpm bitmap data.
+ You do not normally have to bother with this at all: you can use the
+ xfixicon.sh utility from the tools/x11 directory to convert a true
+ colour bitmap to a C file that you only need to link with your own code
+ to set the icon.
+
+
+
+
+In terms of file redistribution, the BeOS platform behaves practically the
+same as the DOS platform. Read section chapter "Dos specifics" in the manual
+to learn more about this.
+
+
+ BeOS Allegro supports the following card parameters for the
+ set_gfx_mode() function:
+
+ GFX_TEXT
+ This closes any graphics mode previously opened with set_gfx_mode.
+
+ GFX_AUTODETECT
+ Let Allegro pick an appropriate graphics driver.
+
+ GFX_AUTODETECT_FULLSCREEN
+ Autodetects a graphics driver, but will only use fullscreen drivers,
+ failing if these are not available on current platform.
+
+ GFX_AUTODETECT_WINDOWED
+ Same as above, but uses only windowed drivers.
+
+ GFX_SAFE
+ Special driver for when you want to reliably set a graphics mode and
+ don't really care what resolution. See the set_gfx_mode()
+ documentation for details.
+
+ GFX_BWINDOWSCREEN_ACCEL
+ Fullscreen exclusive mode. Supports only resolutions higher or equal
+ to 640x480, and uses hardware acceleration if available.
+
+ GFX_BWINDOWSCREEN
+ Works the same as GFX_BWINDOWSCREEN_ACCEL, but disables acceleration.
+
+ GFX_BDIRECTWINDOW
+ Fast windowed mode using the BDirectWindow class. Not all graphics
+ cards support this.
+
+ GFX_BWINDOW
+ Normal windowed mode using the BWindow class. Slow but always works.
+
+ GFX_BWINDOW_OVERLAY
+ Fullscreen mode using BWindow with a BBitmap overlay. This mode isn't
+ supported by all graphics cards, only supports 15, 16 and 32-bit color
+ depths, but allows any fullscreen resolution, even low ones that are
+ normally unavailable under BeOS.
+
qnx_get_window — Retrieves a handle to the window used by Allegro.
+
+
+
+In terms of file redistribution, the QNX platform behaves practically the
+same as the DOS platform. Read section chapter "Dos specifics" in the manual
+to learn more about this.
+
+
+ QNX Allegro supports the following card parameters for the
+ set_gfx_mode() function:
+
+ GFX_TEXT
+ This closes any graphics mode previously opened with set_gfx_mode.
+
+ GFX_AUTODETECT
+ Let Allegro pick an appropriate graphics driver.
+
+ GFX_AUTODETECT_FULLSCREEN
+ Autodetects a graphics driver, but will only use fullscreen drivers,
+ failing if these are not available on current platform.
+
+ GFX_AUTODETECT_WINDOWED
+ Same as above, but uses only windowed drivers.
+
+ GFX_SAFE
+ Special driver for when you want to reliably set a graphics mode and
+ don't really care what resolution. See the set_gfx_mode()
+ documentation for details.
+
+ GFX_PHOTON
+ Alias for GFX_PHOTON_ACCEL.
+
+ GFX_PHOTON_ACCEL
+ Fullscreen exclusive mode through Photon, running with hardware
+ acceleration enabled.
+
+ GFX_PHOTON_SOFT
+ Fullscreen exclusive mode that only uses software drawing, rather than
+ any hardware accelerated features.
+
+ GFX_PHOTON_SAFE
+ Simplified fullscreen exclusive driver that doesn't support any
+ hardware acceleration, video or system bitmaps, etc.
+
+ GFX_PHOTON_WIN
+ The regular windowed Photon driver, running in color conversion mode
+ when the color depth doesn't match that of the Photon desktop. Color
+ conversion is much slower than direct drawing. Note that, mainly for
+ performance reasons, this driver requires the width of the screen to
+ be a multiple of 4.
+
+The following functions provide a platform specific interface to seamlessly
+integrate Allegro into general purpose QNX programs. To use these routines,
+you must include qnxalleg.h after other Allegro headers.
+
+
+ Retrieves a handle to the window used by Allegro. Note that Allegro
+ uses an underlying window even though you don't set any graphics mode,
+ unless you have installed the neutral system driver (SYSTEM_NONE).
+
+
+
+
+In terms of file redistribution, the MacOS X platform behaves practically the
+same as the DOS platform. Read section chapter "Dos specifics" in the manual
+to learn more about this.
+
+
+Allegro programs under MacOS X are Cocoa applications; in order to hide all
+the Cocoa interfacing to the enduser, you need to add the END_OF_MAIN()
+macro right after your main() function. This is a necessary step: if you omit
+it, your program will not compile.
+
+
+The END_OF_MAIN() macro simply does some magic to make sure your program
+executes another function before your main(); this function is defined into
+the liballeg-main.a static library, which is automatically linked if you use
+the allegro-config script when linking. Otherwise be sure you link against it
+unless you want to get undefined symbol errors.
+
+
+To behave nicely with the MacOS X user interface, Allegro apps will provide a
+standard application menu with the "Quit" menu item in it. The default
+behaviour when the user hits Command-Q or selects "Quit" is to do nothing.
+To override this behaviour you must call the set_close_button_callback() function; under MacOS
+X the supplied callback will be used either if the user clicks the window
+close button either on Command-Q or "Quit" selection. In this last case the
+application will not shutdown, but you are supposed to set some quit flag
+in your callback and check for it on a regular basis in your main program
+loop.
+
+
+If you would like to use InterfaceBuilder to design a more
+fully-featured menu, Allegro will automatically load it if you create
+a bundle for your application. The use of InterfaceBuilder is beyond
+the scope of this document. Briefly, you need to create a Nib, called
+MainMenu.nib, containing a main menu and a controller. Then, when you
+create the bundle, install MainMenu.nib into the Contents/Resources
+subdirectory. Note that the actions attached to the menu items will be
+called from a different thread than the one in which your Allegro code
+is running. Therefore you should not do any work there (especially,
+don't call Allegro functions.) Instead, set a variable, and test it in
+your main loop.
+
+
+ MacOS X Allegro supports the following card parameters for the
+ set_gfx_mode() function:
+
+ GFX_TEXT
+ This closes any graphics mode previously opened with set_gfx_mode.
+
+ GFX_AUTODETECT
+ Let Allegro pick an appropriate graphics driver.
+
+ GFX_AUTODETECT_FULLSCREEN
+ Autodetects a graphics driver, but will only use fullscreen drivers,
+ failing if these are not available on current platform.
+
+ GFX_AUTODETECT_WINDOWED
+ Same as above, but uses only windowed drivers.
+
+ GFX_SAFE
+ Special driver for when you want to reliably set a graphics mode and
+ don't really care what resolution. See the set_gfx_mode()
+ documentation for details.
+
+ GFX_QUARTZ_FULLSCREEN
+ Fullscreen exclusive mode, using the CGDirectDisplay interface.
+ Supports only resolutions higher or equal to 640x480, and uses
+ hardware acceleration if available.
+
+ GFX_QUARTZ_WINDOW
+ Windowed mode using QuickDraw in a Cocoa window.
+
+ The MacOS X sound functions support the following digital soundcards:
+
+ DIGI_AUTODETECT - let Allegro pick a digital sound driver
+ DIGI_NONE - no digital sound
+ DIGI_CORE_AUDIO - CoreAudio digital output (OS >= X.2 required)
+ DIGI_SOUND_MANAGER - Carbon Sound Manager digital output
+
+Here's a quick summary of things that may cause problems when moving your
+code from one platform to another (you can find a more detailed version of
+this in the docs section of the Allegro website).
+
+
+The Windows, Unix and MacOS X versions require you to write END_OF_MAIN()
+after your main() function. This is used to magically turn an ISO C style
+main() into a Windows style WinMain(), or by the Unix code to grab a copy
+of your argv[] parameter, or by the MacOS X code to shell the user main()
+inside a Cocoa application.
+
+
+On many platforms Allegro runs very slowly if you rely on it in order to
+automatically lock bitmaps when drawing onto them. For good performance,
+you need to call acquire_bitmap() and release_bitmap() yourself, and try
+to keep the amount of locking to a minimum.
+
+
+The Windows version may lose the contents of video memory if the user
+switches away from your program, so you need to deal with that.
+
+
+None of the currently supported platforms require input polling, but it is
+possible that some future ones might, so if you want to ensure 100%
+portability of your program, you should call poll_mouse() and
+poll_keyboard() in all the relevant places.
+
+
+On Unix the shared files by Allegro (like `language.dat') may require a
+special use due to the nature of distributing the resources in separate paths
+instead of putting everything in the same directory. Check the beginning of
+your platform's specific chapter to learn more about this.
+
+
+Allegro defines a number of standard macros that can be used to check
+various attributes of the current platform:
+
+
+ALLEGRO_PLATFORM_STR
+ Text string containing the name of the current platform.
+
+
+ALLEGRO_DOS
+ALLEGRO_DJGPP
+ALLEGRO_WATCOM
+ALLEGRO_WINDOWS
+ALLEGRO_MSVC
+ALLEGRO_MINGW32
+ALLEGRO_BCC32
+ALLEGRO_UNIX
+ALLEGRO_LINUX
+ALLEGRO_BEOS
+ALLEGRO_QNX
+ALLEGRO_DARWIN
+ALLEGRO_MACOSX
+ALLEGRO_GCC
+ Defined if you are building for a relevant system. Often several of these
+ will apply, eg. DOS+Watcom, or Windows+GCC+MinGW.
+
+
+ALLEGRO_AMD64
+ALLEGRO_I386
+ALLEGRO_BIG_ENDIAN
+ALLEGRO_LITTLE_ENDIAN
+ Defined if you are building for a processor of the relevant type.
+
+
+ALLEGRO_MULTITHREADED
+ Defined if the library is internally multi-threaded on this system.
+
+
+ALLEGRO_USE_CONSTRUCTOR
+ Defined if the compiler supports constructor/destructor functions.
+
+
+ALLEGRO_VRAM_SINGLE_SURFACE
+ Defined if the screen is a single large surface that is then partitioned
+ into multiple video sub-bitmaps (eg. DOS), rather than each video bitmap
+ being a totally unique entity (eg. Windows).
+
+
+ALLEGRO_CONSOLE_OK
+ Defined if when you are not in a graphics mode, there is a text mode
+ console that you can printf() to, and from which the user could
+ potentially redirect stdout to capture it even while you are in a
+ graphics mode. If this define is absent, you are running in an
+ environment like Windows that has no stdout at all.
+
+
+ALLEGRO_MAGIC_MAIN
+ Defined if Allegro uses a magic main, i.e takes over the main() entry
+ point and turns it into a secondary entry point suited to its needs.
+
+
+ALLEGRO_LFN
+ Non-zero if long filenames are supported, or zero if you are limited to
+ 8.3 format (in the DJGPP version, this is a variable depending on the
+ runtime environment).
+
+
+LONG_LONG
+ Defined to whatever represents a 64-bit "long long" integer for the
+ current compiler, or not defined if that isn't supported.
+
+
+OTHER_PATH_SEPARATOR
+ Defined to a path separator character other than a forward slash for
+ platforms that use one (eg. a backslash under DOS and Windows), or
+ defined to a forward slash if there is no other separator character.
+
+
+DEVICE_SEPARATOR
+ Defined to the filename device separator character (a colon for DOS and
+ Windows), or to zero if there are no explicit devices in paths (Unix).
+
+
+Allegro can be customized at compile time to a certain extent with the
+following macros:
+
+
+ALLEGRO_NO_MAGIC_MAIN
+ If you define this prior to including Allegro headers, Allegro won't
+ touch the main() entry point. This effectively removes the requirement
+ on a program to be linked against the Allegro library when it includes
+ the allegro.h header file. Note that the configuration and file routines
+ are not guaranteed to work on Unix systems when this symbol is defined.
+ Moreover, on Darwin/MacOS X systems, this symbol simply prevents the
+ program from being linked against the Allegro library! This highly non
+ portable feature is primarily intended to be used under Windows.
+
+
+ALLEGRO_USE_CONSOLE
+ If you define this prior to including Allegro headers, Allegro will be
+ set up for building a console application rather than the default GUI
+ program on some platforms (especially Windows).
+
+
+ALLEGRO_NO_STD_HEADER
+ If you define this prior to including Allegro headers, Allegro will not
+ automatically include some standard headers (eg <stddef.h>) its own
+ headers depend upon.
+
+
+ALLEGRO_NO_KEY_DEFINES
+ If you define this prior to including Allegro headers, Allegro will omit
+ the definition of the KEY_* constants, which may clash with other headers.
+
+
+ALLEGRO_NO_FIX_ALIASES
+ The fixed point functions used to be named with an "f" prefix instead of
+ "fix", eg. fixsqrt() used to be fsqrt(), but were renamed due to conflicts
+ with some libc implementations. So backwards compatibility aliases are
+ provided as static inline functions which map the old names to the new
+ names, eg. fsqrt() calls fixsqrt(). If you define this symbol prior to
+ including Allegro headers, the aliases will be turned off.
+
+
+ALLEGRO_NO_FIX_CLASS
+ If you define this symbol prior to including Allegro headers in a C++
+ source file, the 'fix' class will not be made available. This mitigates
+ problems with the 'fix' class's overloading getting in the way.
+
+
+ALLEGRO_NO_VHLINE_ALIAS
+ The `curses' API also defines functions called vline() and hline().
+ To avoid a linker conflict when both libraries are used, we have
+ internally renamed our functions and added inline function aliases which
+ remap vline() and hline(). This should not be noticable to most users.
+
+
+ If you define ALLEGRO_NO_VHLINE_ALIAS prior to including Allegro headers,
+ Allegro will not define the vline() and hline() aliases, e.g. so you can
+ include curses.h and allegro.h in the same module.
+
+
+ALLEGRO_NO_CLEAR_BITMAP_ALIAS
+ If you define this prior to including Allegro headers, Allegro will not
+ define the clear() backwards compatibility alias to clear_bitmap().
+
+
+ALLEGRO_NO_COMPATIBILITY
+ If you define this prior to including Allegro headers, Allegro will not
+ include the backward compatibility layer. It is undefined by default so
+ old programs can still be compiled with the minimum amount of issues,
+ but you should define this symbol if you intend to maintain your code
+ up to date with the latest versions of Allegro. It automatically turns
+ off all backwards compatibility aliases.
+
+
+Allegro also defines a number of standard macros that can be used to
+insulate you from some of the differences between systems:
+
+
+INLINE
+ Use this in place of the regular "inline" function modifier keyword, and
+ your code will work correctly on any of the supported compilers.
+
+
+RET_VOLATILE
+ Use this to declare a function with a volatile return value.
+
+
+ZERO_SIZE_ARRAY(type, name)
+ Use this to declare zero-sized arrays in terminal position inside
+ structures, like in the BITMAP structure. These arrays are effectively
+ equivalent to the flexible array members of ISO C99.
+
+
+AL_CONST
+ Use this in place of the regular "const" object modifier keyword, and
+ your code will work correctly on any of the supported compilers.
+
+
+AL_RAND()
+ On platforms that require it, this macro does a simple shift
+ transformation of the libc rand() function, in order to improve the
+ perceived randomness of the output series in the lower 16 bits.
+ Where not required, it directly translates into a rand() call.
+
+
+
+
+Some people complain that Allegro produces very large executables. This is
+certainly true: with the DJGPP version, a simple "hello world" program will
+be about 200k, although the per-executable overhead is much less for
+platforms that support dynamic linking. But don't worry, Allegro takes up a
+relatively fixed amount of space, and won't increase as your program gets
+larger. As George Foot so succinctly put it, anyone who is concerned about
+the ratio between library and program code should just get to work and write
+more program code to catch up :-)
+
+
+Having said that, there are several things you can do to make your programs
+smaller:
+
+For all platforms, you can use an executable compressor called UPX, which
+is available at http://upx.sourceforge.net/. This usually manages a
+compression ratio of about 40%.
+
+When using DJGPP: for starters, read the DJGPP FAQ section 8.14, and take
+note of the -s switch. And don't forget to compile your program with
+optimisation enabled!
+
+If a DOS program is only going to run in a limited number of graphics modes,
+you can specify which graphics drivers you would like to include with the
+code:
+
+This construct must be included in only one of your C source files. The
+ordering of the names is important, because the autodetection routine works
+down from the top of the list until it finds the first driver that is able
+to support the requested mode. I suggest you stick to the default ordering
+given above, and simply delete whatever entries you aren't going to use.
+
+If your DOS program doesn't need to use all the possible color depths, you
+can specify which pixel formats you want to support with the code:
+
+Removing any of the color depths will save quite a bit of space, with the
+exception of the 15 and 16-bit modes: these share a great deal of code, so
+if you are including one of them, there is no reason not to use both. Be
+warned that if you try to use a color depth which isn't in this list, your
+program will crash horribly!
+
+In the same way as the above, you can specify which DOS sound drivers you
+want to support with the code:
+
+The standard driver includes support for the dual joysticks, increased
+numbers of buttons, Flightstick Pro, and Wingman Extreme, because these are
+all quite minor variations on the basic code.
+
+If you are _really_ serious about this size, thing, have a look at the top
+of include/allegro/alconfig.h and you will see the lines:
+
+If you comment out any of these definitions and then rebuild the library,
+you will get a version without any support for the absent color depths,
+which will be even smaller than using the DECLARE_COLOR_DEPTH_LIST() macro.
+Removing the ALLEGRO_COLOR16 define will get rid of the support for both 15
+and 16-bit hicolor modes, since these share a lot of the same code.
+
+Note: the aforementioned methods for removing unused hardware drivers only
+apply to statically linked versions of the library, eg. DOS. On Windows and
+Unix platforms, you can build Allegro as a DLL or shared library, which
+prevents these methods from working, but saves so much space that you
+probably won't care about that. Removing unused color depths from alconfig.h
+will work on any platform, though.
+
+
+If you are distributing a copy of the setup program along with your game,
+you may be able to get a dramatic size reduction by merging the setup code
+into your main program, so that only one copy of the Allegro routines will
+need to be linked. See setup.txt for details. In the DJGPP version, after
+compressing the executable, this will probably save you about 200k compared
+to having two separate programs for the setup and the game itself.
+
+
+
+
TRACE — Debugging helper macro to trace messages.
+
+
+
+There are three versions of the Allegro library: the normal optimised code,
+one with extra debugging support, and a profiling version. See the platform
+specific readme files for information about how to install and link with
+these alternative libs. Although you will obviously want to use the
+optimised library for the final version of your program, it can be very
+useful to link with the debug lib while you are working on it, because this
+will make debugging much easier, and includes assert tests that will help to
+locate errors in your code at an earlier stage. Allegro also contains some
+debugging helper functions:
+
+
+ Debugging helper macro. Normally compiles away to nothing, but if you
+ defined the preprocessor symbol DEBUGMODE before including Allegro headers,
+ it will check the supplied condition and call al_assert() if it fails,
+ whose default action is to stop the program and report the assert. You can
+ use this macro even when Allegro has not been initialised. Example:
+
+ Debugging helper macro. Normally compiles away to nothing, but if you
+ defined the preprocessor symbol DEBUGMODE before including Allegro headers,
+ it passes the supplied message given in ASCII format to al_trace().
+ Example:
+
+ Supplies a custom handler function for dealing with assert failures. Your
+ callback will be passed a formatted error message in ASCII, and should
+ return non-zero if it has processed the error, or zero to continue with
+ the default actions. You could use this to ignore assert failures, or to
+ display the error messages on a graphics mode screen without aborting the
+ program. Example:
+
+ int show_but_continue(const char *text)
+ {
+ alert("Uh oh...", "Fasten your seat belts.", text,
+ "&Go on!", NULL, 'g', 0);
+ return 1;
+ }
+ ...
+ register_assert(show_but_continue);
+ ASSERT(0); /* This won't crash the program now. */
+ Supplies a custom handler function for dealing with trace output. Your
+ callback will be passed a formatted error message in ASCII, and should
+ return non-zero if it has processed the message, or zero to continue with
+ the default actions. You could use this to ignore trace output, or to
+ display the messages on a second monochrome monitor, etc. Example:
+
+ int network_broadcaster(const char *text)
+ {
+ int f;
+
+ for (int f = 0; f < connected_clients; f++)
+ send_msg_to_client(client[f], text);
+
+ return 0; /* Let normal tracing occur. */
+ }
+ ...
+ register_trace_handler(network_broadcaster);
+ TRACE("Networked tracing activated\n");
+ Raises an assert for an error at the specified file and line number. The
+ file parameter is always given in ASCII format. By default, this will call
+ the system driver's assert handler. If there is none, the error will be
+ sent to stderr and the program will abort. However, if the environment
+ variable ALLEGRO_ASSERT is set, this function writes a message into the
+ file specified by the environment variable and program execution will
+ continue. If none of this behaviours is wanted, you can override them with
+ a custom assert handler.
+
+
+ You will usually want to use the ASSERT() macro instead of calling this
+ function directly.
+
+
+
+ Outputs a debugging trace message, using a printf() format string given
+ in ASCII. If you have installed a custom trace handler it uses that, or
+ if the environment variable ALLEGRO_TRACE is set it writes into the file
+ specified by the environment, otherwise it writes the message to
+ "allegro.log" in the current directory. You will usually want to use the
+ TRACE() macro instead of calling this function directly.
+
+
+
+
+
+There are a number of options that you can use to control exactly how
+Allegro will be compiled. On Unix platforms, you do this by passing arguments
+to the configure script (run "configure --help" for a list), but on other
+platforms you can set the following environment variables:
+
+ DEBUGMODE=1
+ Selects a debug build, rather than the normal optimised version.
+
+ DEBUGMODE=2
+ Selects a build intended to debug Allegro itself, rather than the
+ normal optimised version.
+
+ PROFILEMODE=1
+ Selects a profiling build, rather than the normal optimised version.
+
+ WARNMODE=1
+ Selects strict compiler warnings. If you are planning to work on Allegro
+ yourself, rather than just using it in your programs, you should be sure
+ to have this mode enabled.
+
+ STATICLINK=1 (MinGW, MSVC, BeOS, MacOS X only)
+ Link as a static library, rather than the default dynamic library.
+
+ STATICRUNTIME=1 (MSVC only)
+ Link against static runtime libraries, rather than the default dynamic
+ runtime libraries.
+
+ TARGET_ARCH_COMPAT=[cpu] (GCC-based platforms only)
+ This option will optimize for the given processor while maintaining
+ compatibility with older processors.
+ Example: set TARGET_ARCH_COMPAT=i586
+
+ TARGET_ARCH_EXCL=[cpu] (GCC-based platforms only)
+ This option will optimize for the given processor. Please note that
+ using it will cause the code to *NOT* run on older processors.
+ Example: set TARGET_ARCH_EXCL=i586
+
+ TARGET_OPTS=[opts] (GCC-based platforms only)
+ This option allows you to customize general compiler optimisations.
+
+ TARGET_ARCH_EXCL=[opts] (MSVC only)
+ This option allows you to optimize exclusively for a given architecture.
+ Pass B to optimize for a PentiumPro or 7 to optimize for Pentium 4. Note
+ that the options you can pass may be different between MSVC 6 and 7.
+ Example: set TARGET_ARCH_EXCL=7
+
+ CROSSCOMPILE=1 (DJGPP, MinGW only)
+ Allows you to build the library under Linux by using a cross-compiler.
+
+ ALLEGRO_USE_C=1 (GCC-based platforms only)
+ Allows you to build the library using C drawing code instead of the usual
+ asm routines. This is only really useful for testing, since the asm
+ version is faster.
+
+ UNIX_TOOLS=1
+ Instructs the build process to use Unix-like tools instead of DOS tools.
+ Note that you usually don't need to set it because the build proces will
+ try to autodetect this configuration.
+
+ COMPILER_MSVC7=1 (MSVC only)
+ Enables special optimizations for MSVC 7 (the default is MSVC 6). You don't
+ normally need to set this flag since fix.bat msvc7 should do the same
+ thing and is the prefered way of doing this.
+
+ COMPILER_ICL=1 (MSVC only)
+ Instructs the build process to use the Intel commandline compiler icl rather
+ than Microsoft's commandline compiler cl. You don't normally need to pass
+ this flag since fix.bat icl should do the same thing and is the
+ prefered way of doing this. Do not try COMPILER_MSVC7=1 and COMPILER_ICL=1
+ at the same time.
+
+If you only want to recompile a specific test program or utility, you can
+specify it as an argument to make, eg. "make demo" or "make grabber". The
+makefiles also provide some special pseudo-targets:
+
+ 'info' (Unix only)
+ Tells you which options this particular build of Allegro will use.
+ Especially useful to verify that the required libraries were detected
+ and you won't get a 'half-featured' Allegro.
+
+ 'default'
+ The normal build process. Compiles the current library version (one of
+ optimised, debugging, or profiling, selected by the above environment
+ variables), builds the test and example programs, and converts the
+ documentation files.
+
+ 'all' (non-Unix only)
+ Compiles all three library versions (optimised, debugging, and
+ profiling), builds the test and example programs, and converts the
+ documentation files.
+
+ 'lib'
+ Compiles the current library version (one of optimised, debugging, or
+ profiling, selected by the above environment variables).
+
+ 'modules' (Unix only)
+ This will compile all the modules currently configured. The 'lib' and
+ 'modules' targets together are needed to build a working copy of the
+ library, without documentation or programs.
+
+ 'install'
+ Copies the current library version (one of optimised, debugging, or
+ profiling, selected by the above environment variables), into your
+ compiler lib directory, recompiling it as required, and installs the
+ Allegro headers.
+
+ 'install-lib' (Unix only)
+ You can use this to install the library and the modules only, without
+ documentation or programs. Use the 'install' target to install
+ everything.
+
+ 'installall' (non-Unix only)
+ Copies all three library versions (optimised, debugging, and profiling),
+ into your compiler lib directory, recompiling them as required, and
+ installs the Allegro headers.
+
+ 'uninstall'
+ Removes the Allegro library and headers from your compiler directories.
+
+ 'docs'
+ Converts the documentation files from the ._tx sources.
+
+ 'chm-docs' (Windows only)
+ Creates a compiled HTML file from the previously generated html output.
+ This is not a default target, since you need Microsoft's HTML compiler
+ (http://go.microsoft.com/fwlink/?LinkId=14188),
+ and it has to be installed somewhere in your PATH. Also, this only works
+ if you use '@multiplefiles' (see the top of docs/src/allegro._tx).
+
+ 'docs-dvi' (Unix only)
+ Creates the allegro.dvi device independent documentation file. This is
+ not a default target, since you need the texi2dvi tool to create it. The
+ generated file is especially prepared to be printed on paper.
+
+ 'docs-ps' or 'docs-gzipped-ps' or 'docs-bzipped-ps' (Unix only)
+ Creates a Postcript file from the previously generated DVI file. This is
+ not a default target, since you need the texi2dvi and dvips tools to
+ create it. The second and third targets compress the generated Postscript
+ file. The generated file is especially prepared to be printed on paper.
+
+ 'docs-pdf' (Unix only)
+ Creates a PDF file. This is not a default target, since you need the
+ texi2pdf tool to create it. The generated file is especially prepared to
+ be printed on paper, and it also has hyperlinks.
+
+ 'docs-devhelp' (Unix only)
+ Creates normal HTML documentation with an additional xml index file which
+ can be used by tools like Devhelp (http://www.devhelp.net/) to
+ show context sensitive help within any editor using Devhelp, like for
+ example http://anjuta.sourceforge.net/. The Allegro 'book' will be
+ created in `docs/devhelp/allegro.devhelp', you have to install it
+ manually.
+
+ 'install-man' (Unix and Mac OS X only)
+ Generates Unix man pages for each Allegro function or variable and
+ installs them.
+
+ 'install-gzipped-man' or 'install-bzipped-man' (Unix only)
+ Like install-man, but also compresses the manual pages after installing
+ them (run only one of these).
+
+ 'uninstall-man' (Unix)
+ Uninstalls any man pages previously installed with 'install-man',
+ 'install-gzipped-man', or 'install-bzipped-man'.
+
+ 'install-info' or 'install-gzipped-info' or 'install-bzipped-info'
+ (Unix only)
+ Converts the documentation to Info format and installs it. The second
+ and third targets compress the info file after installing it (run only
+ one of them).
+
+ 'uninstall-info' (Unix only)
+ Uninstalls any man pages previously installed with 'install-info',
+ 'install-gzipped-info', or 'install-bzipped-info'.
+
+ 'clean'
+ Removes generated object and library files, either to recover disk space
+ or to force a complete rebuild the next time you run make. This target is
+ designed so that if you run a "make install" followed by "make clean",
+ you will still have a functional version of Allegro.
+
+ 'distclean'
+ Like "make clean", but more so. This removes all the executable files and
+ the documentation, leaving you with only the same files that are included
+ when you unzip a new Allegro distribution.
+
+ 'veryclean'
+ Use with extreme caution! This target deletes absolutely all generated
+ files, including some that may be non-trivial to recreate. After you run
+ "make veryclean", a simple rebuild will not work: at the very least you
+ will have to run "make depend", and perhaps also fixdll.bat if you are
+ using the Windows library. These targets make use of non-standard tools
+ like SED, so unless you know what you are doing and have all this stuff
+ installed, you should not use them.
+
+ 'compress' (DJGPP, MinGW and MSVC only)
+ Uses the DJP or UPX executable compressors (whichever you have installed)
+ to compress the example executables and utility programs, which can
+ recover a significant amount of disk space.
+
+ 'depend'
+ Regenerates the dependency files (obj/*/makefile.dep). You need to run
+ this after "make veryclean", or whenever you add new headers to the
+ Allegro sources.
+
+With Allegro comes quite a bunch of examples, which go from the simple
+introductory `Hello world' to more complicated programs featuring truecolor
+blending effects. This chapter describes these examples which you can find
+in the allegro/examples folder. You don't have to go through them in the same
+order as this documentation, but doing so you will learn the basic functions
+and avoid missing any important bit of information.
+
+
+ This program demonstrates the use of memory bitmaps. It creates
+ a small temporary bitmap in memory, draws some circles onto it,
+ and then blits lots of copies of it onto the screen.
+
+
+
+ This program demonstrates how to manipulate the palette. It draws
+ a set of concentric circles onto the screen and animates them by
+ cycling the palette.
+
+
+
+ This program demonstrates how to write directly to video memory.
+ It implements a simple fire effect, first by calling getpixel() and
+ putpixel(), then by accessing video memory directly a byte at a
+ time, and finally using block memory copy operations.
+
+
+
+ This program demonstrates the use of double buffering.
+ It moves a circle across the screen, first just erasing and
+ redrawing directly to the screen, then with a double buffer.
+
+
+
+ This program demonstrates how to use fixed point numbers, which
+ are signed 32-bit integers storing the integer part in the
+ upper 16 bits and the decimal part in the 16 lower bits. This
+ example also uses the unusual approach of communicating with
+ the user exclusively via the allegro_message() function.
+
+
+
+ This program demonstrates how to get mouse input. The
+ first part of the test retrieves the raw mouse input data
+ and displays it on the screen without using any mouse
+ cursor. When you press a key the standard arrow-like mouse
+ cursor appears. You are not restricted to this shape,
+ and a second keypress modifies the cursor to be several
+ concentric colored circles. They are not joined together,
+ so you can still see bits of what's behind when you move the
+ cursor over the printed text message.
+
+
+
+ This program demonstrates how to use the timer routines.
+ These can be a bit of a pain, because you have to be sure
+ you lock all the memory that is used inside your interrupt
+ handlers. The first part of the example shows a basic use of
+ timing using the blocking function rest(). The second part
+ shows how to use three timers with different frequencies in
+ a non blocking way.
+
+
+
+ This program demonstrates how to access the keyboard. The
+ first part shows the basic use of readkey(). The second part
+ shows how to extract the ASCII value. Next come the scancodes.
+ The fourth test detects modifier keys like alt or shift. The
+ fifth test requires some focus to be passed. The final step
+ shows how to use the global key array to read simultaneous
+ keypresses.
+ The last method to detect key presses are keyboard callbacks.
+ This is demonstrated by by installing a keyboard callback,
+ which marks all pressed keys by drawing to a grid.
+
+
+
+ This program uses the Allegro library to detect and read the value
+ of a joystick. The output of the program is a small target sight
+ on the screen which you can move. At the same time the program will
+ tell you what you are doing with the joystick (moving or firing).
+
+
+
+ This program demonstrates how to play samples. You have to
+ use this example from the commandline to specify as first
+ parameter a WAV or VOC sound file to play. If the file is
+ loaded successfully, the sound will be played in an infinite
+ loop. While it is being played, you can use the left and right
+ arrow keys to modify the panning of the sound. You can also
+ use the up and down arrow keys to modify the pitch.
+
+
+
+ This program demonstrates how to use the GUI routines. From
+ the simple dialog controls that display a text or a bitmap to
+ more complex multiple choice selection lists, Allegro provides
+ a framework which can be customised to suit your needs.
+
+
+
+ A follow up of the exgui.c example showing how to customise the
+ default Allegro framework. In this case a dialog procedure
+ animates a graphical clock without disrupting other GUI
+ dialogs. A more simple option shows how to dynamically change
+ the font used by all GUI elements.
+
+
+
+ This program demonstrates the use of the 16-bit Unicode text
+ encoding format with Allegro. The example displays a message
+ translated to different languages scrolling on the screen
+ using an external font containing the required characters to
+ display those messages.
+
+
+ Note how the Allegro unicode string functions resemble the
+ functions you can find in the standard C library, only these
+ handle Unicode on all platforms.
+
+
+
+ This program demonstrates how to load and display a bitmap
+ file. You have to use this example from the commandline to
+ specify as first parameter a graphic file in one of Allegro's
+ supported formats. If the file is loaded successfully,
+ it will be displayed until you press a key.
+
+
+
+ This example demonstrates how to use pcx files, palettes and stretch
+ blits. It loads a pcx file, sets its palette and does some random
+ stretch_blits. Don't worry - it's VERY slowed down using vsync().
+
+
+
+ This is a very simple program showing how to use the allegro
+ config (ini file) routines. A first look at the example
+ shows nothing more than a static graphic and the wait for
+ a keypress. However, the way this graphic is displayed is
+ configured through a custom exconfig.ini file which is loaded
+ manually. From this file the example obtains parameters like
+ fullscreen/windowed mode, a specific graphic resolution to set
+ up, which graphic to show, how to blit it on the screen, etc.
+
+
+
+ This program demonstrates how to access the contents of an
+ Allegro datafile (created by the grabber utility). The example
+ loads the file `example.dat', then blits a bitmap and shows
+ a font, both from this datafile.
+
+
+
+ This example demonstrates how to use datafiles, various sprite
+ drawing routines and flicker-free animation.
+
+
+ Why is the animate() routine coded in that way? As you
+ probably know, VIDEO RAM is much slower than "normal"
+ RAM, so it's advisable to reduce VRAM blits to a minimum.
+ Drawing sprite on the screen (meaning in VRAM) and then
+ clearing a background for it is not very fast. This example
+ uses a different method which is much faster, but require a
+ bit more memory.
+
+
+ First the buffer is cleared (it's a normal BITMAP), then the
+ sprite is drawn on it, and when the drawing is finished this
+ buffer is copied directly to the screen. So the end result is
+ that there is a single VRAM blit instead of blitting/clearing
+ the background and drawing a sprite on it. It's a good method
+ even when you have to restore the background. And of course,
+ it completely removes any flickering effect.
+
+
+ When one uses a big (ie. 800x600 background) and draws
+ something on it, it's wise to use a copy of background
+ somewhere in memory and restore background using this
+ "virtual background". When blitting from VRAM in SVGA modes,
+ it's probably, that drawing routines have to switch banks on
+ video card. I think, I don't have to remind how slow is it.
+
+
+ Note that on modern systems, the above isn't true anymore, and
+ you usually get the best performance by caching all your
+ animations in video ram and doing only VRAM->VRAM blits, so
+ there is no more RAM->VRAM transfer at all anymore. And usually,
+ such transfers can run in parallel on the graphics card's
+ processor as well, costing virtually no main cpu time at all.
+ See the exaccel example for an example of this.
+
+
+
+ This program demonstrates how to access the contents of an Allegro
+ datafile (created by the grabber utility) linked to the exe by the
+ exedat tool. It is basically the exdata example with minor
+ modifications.
+
+
+ You may ask: how do you compile, append and exec your program?
+
+
+ Answer: like this...
+
+
+ 1) Compile your program like normal. Use the magic filenames with '#'
+ to load your data where needed.
+
+
+ 2) Once you compressed your program, run "exedat foo.exe data.dat"
+
+
+ 3) Finally run your program.
+
+
+ Note that appending data to the end of binaries may not be portable
+ accross all platforms supported by Allegro.
+
+
+
+ This program demonstrates how to use the lighting and
+ translucency functions. The first part of the example will
+ show a dark screen iluminated by a spotlight you can move
+ with your mouse. After a keypress the example shows the full
+ bitmap and the spotlight changes to be a reduced version of
+ the background with 50% of translucency.
+
+
+ The translucency effect is easy to do in all color depths.
+ However, the lighting effect has to be performed in a different
+ way depending on whether the screen is in 8bit mode or another
+ color depth. This is because additive drawing mode uses a
+ different set of routines for truecolor modes.
+
+
+
+ This program shows how to specify colors in the various different
+ truecolor pixel formats. The example shows the same screen (a few
+ text lines and three coloured gradients) in all the color depth
+ modes supported by your video card. The more color depth you have,
+ the less banding you will see in the gradients.
+
+
+
+ This program demonstrates how to create custom graphic effects
+ with the create_color_table function. Allegro drawing routines
+ are affected by any color table you might have set up. In
+ the first part of this example, a greyscale color table is
+ set. The result is that a simple rectfill call, instead of
+ drawing a rectangle with color zero, uses the already drawn
+ pixels to determine the pixel to be drawn (read the comment
+ of return_grey_color() for a precise description of the
+ algorithm). In the second part of the test, the color table
+ is changed to be an inverse table, meaning that any pixel
+ drawn will be shown as its color values had been inverted.
+
+
+
+ This program shows how to convert colors between the different
+ color-space representations. The central area of the screen
+ will display the current color. On the top left corner of the
+ screen, three sliders allow you to modify the red, green and
+ blue value of the color. On the bottom right corner of the
+ screen, three sliders allow you to modify the hue, saturation
+ and value of the color. The color bars beneath the sliders
+ show what the resulting color will look like when the slider
+ is dragged to that position.
+
+
+ Additionally this example also shows how to "inherit" the
+ behaviour of a GUI object and extend it, here used to create
+ the sliders.
+
+
+
+ This program demonstrates how to draw gouraud shaded (lit)
+ sprites. In an apparently black screen, a planet like sprite
+ is drawn close to the middle of the screen. In a similar
+ way to how the first test of extrans works, you move the
+ cursor on the screen with the mouse. Attached to this mouse
+ you can imagine a virtual spotlight illuminating the scene
+ around. Depending on where the mouse is, the goraud shaded
+ sprite will show the direction of the light.
+
+
+
+ This program demonstrates how to use the translucency functions
+ in truecolor video modes. Two image files are loaded from
+ disk and displayed moving slowly around the screen. One of
+ the images will be tinted to different colors. The other
+ image will be faded out with a varying alpha strength, and
+ drawn on top of the other image.
+
+
+
+ This program demonstrates how to load and display bitmap files
+ in truecolor video modes, and how to crossfade between them.
+ You have to use this example from the commandline to specify
+ as parameters a number of graphic files. Use at least two
+ files to see the graphical effect. The example will crossfade
+ from one image to another with each keypress until you press
+ the ESC key.
+
+
+
+ This program demonstrates how to use the 32 bit RGBA
+ translucency functions to store an alpha channel along with
+ a bitmap graphic. Two images are loaded from disk. One will
+ be used for the background and the other as a sprite. The
+ example generates an alpha channel for the sprite image,
+ composing the 32 bit RGBA bitmap during runtime, and draws
+ it at the position of the mouse cursor.
+
+
+
+ This program shows one way to implement colored lighting effects
+ in a hicolor video mode. Warning: it is not for the faint of heart!
+ This is by no means the simplest or easiest to understand method,
+ I just thought it was a cool concept that would be worth
+ demonstrating.
+
+
+ The basic approach is to select a 15 or 16 bit screen mode, but
+ then draw onto 24 bit memory bitmaps. Since we only need the bottom
+ 5 bits of each 8 bit color in order to store 15 bit data within a
+ 24 bit location, we can fit a light level into the top 3 bits.
+ The tricky bit is that these aren't actually 24 bit images at all:
+ they are implemented as 8 bit memory bitmaps, and we just store the
+ red level in one pixel, green in the next, and blue in the next,
+ making the total image be three times wider than we really wanted.
+ This allows us to use all the normal 256 color graphics routines
+ for drawing onto our memory surfaces, most importantly the lookup
+ table translucency, which can be used to combine the low 5 bits
+ of color and the top 3 bits of light in a single drawing operation.
+ Some trickery is needed to load 24 bit data into this fake 8 bit
+ format, and of course it needs a custom routine to convert the
+ resulting image while copying it across to the hardware screen.
+
+
+ This program chugs slightly on my p133, but not significantly
+ worse than any double buffering in what amounts to a 1920x640,
+ 256 color resolution. The light blending doesn't seem to slow
+ it down too badly, so I think this technique would be quite usable
+ on faster machines and in lower resolution hicolor modes. The
+ biggest problem is that although you keep the full 15 bit color
+ resolution, you only get 3 bits of light, ie. 8 light levels.
+ You can do some nice colored light patches, but smooth gradients
+ aren't going to work too well :-)
+
+
+
+ This program demonstrates how to use the 3d matrix functions.
+ It isn't a very elegant or efficient piece of code, but it
+ does show the stuff in action. It is left to the reader as
+ an exercise to design a proper model structure and rendering
+ pipeline: after all, the best way to do that sort of stuff
+ varies hugely from one game to another.
+
+
+ The example first shows a screen resolution selection dialog.
+ Then, a number of bouncing 3d cubes are animated. Pressing
+ a key modifies the rendering of the cubes, which can be
+ wireframe, the more complex transparent perspective correct
+ texture mapped version, and many other.
+
+
+
+ This program demonstrates how to use the get_camera_matrix()
+ function to view a 3d world from any position and angle. The
+ example draws a checkered floor through a viewport region
+ on the screen. You can use the keyboard to move around the
+ camera or modify the size of the viewport. The keys that can
+ be used with this example are displayed between brackets at
+ the top of the screen.
+
+
+
+ Euler angles are convenient for storing and creating 3D orientations.
+ However, this program demonstrates that they are not good when
+ interpolating between two different orientations. The problem is
+ solved by using Allegro's quaternion operations.
+
+
+ In this program, two cubes are rotated between random orientations.
+ Notice that although they have the same beginning and ending
+ orientations, they do not follow the same path between orientations.
+
+
+ One cube is being rotated by directly incrementing or decrementing
+ the Euler angles from the starting point to the ending point.
+ This is an intuitive notion, but it is incorrect because it does not
+ cause the object to turn around a single unchanging axis of rotation.
+ The axis of rotation wobbles resulting in the object spinning in
+ strange ways. The object will eventually end up in the orientation
+ that the user intended, but it gets there in a way that is unattractive.
+ Imagine if this method was used to update the position of a camera in a
+ game! Sometimes it would swing wildly and disorient the player.
+
+
+ The other cube is animated using quaternions. This results in a much
+ more pleasing animation because the cube turns around a single axis
+ of rotation.
+
+
+
+ This program draws a 3D starfield (depth-cued) and a polygon
+ starship (controllable with the keyboard cursor keys), using
+ the Allegro math functions.
+
+
+
+ This program demonstrates how to use scanline sorting algo
+ in Allegro (create_scene, clear_scene, ... functions). It
+ also provides an example of how to use the 3D clipping
+ function. The example consists of a flyby through a lot of
+ rotating 3d cubes.
+
+
+
+
+ This program demonstrates how to use Z-buffered polygons and
+ floating point 3D math routines. It also provides a simple
+ way to compute fps (frames per second) using a timer. After
+ selecting a screen resolution through the standard GUI dialog,
+ the example shows two 3D cubes rotating and intersecting each
+ other. Rather than having full polygons incorrectly overlap
+ other polgons due to per-polygon sorting, each pixel is drawn
+ at the correct depth.
+
+
+
+ This program demonstrates how to use hardware scrolling.
+ The scrolling should work on anything that supports virtual
+ screens larger than the physical screen.
+
+
+
+ This program demonstrates the use of triple buffering. Several
+ triangles are displayed rotating and bouncing on the screen
+ until you press a key. Note that on some platforms you
+ can't get real hardware triple buffering. The Allegro code
+ remains the same, but most likely the graphic driver will
+ emulate it. Unfortunately, in these cases you can't expect
+ the animation to be completely smooth and flicker free.
+
+
+
+ This program sets up a 12-bit mode on any 8-bit card, by
+ setting up a 256-colour palette that will fool the eye into
+ grouping two 8-bit pixels into one 12-bit pixel. In order
+ to do this, you make your 256-colour palette with all the
+ combinations of blue and green, assuming green ranges from 0-15
+ and blue from 0-14. This takes up 16x15=240 colours. This
+ leaves 16 colours to use as red (red ranges from 0-15).
+ Then you put your green/blue in one pixel, and your red in
+ the pixel next to it. The eye gets fooled into thinking it's
+ all one pixel.
+
+
+ The example starts setting a normal 256 color mode, and
+ construct a special palette for it. But then comes the trick:
+ you need to write to a set of two adjacent pixels to form a
+ single 12 bit dot. Two eight bit pixels is the same as one 16
+ bit pixel, so after setting the video mode you need to hack
+ the screen bitmap about, halving the width and changing it
+ to use the 16 bit drawing code. Then, once you have packed a
+ color into the correct format (using the makecol12() function
+ below), any of the normal Allegro drawing functions can be
+ used with this 12 bit display!
+
+
+ Things to note:
+
+
+
The horizontal width is halved, so you get resolutions
+ like 320x480, 400x600, and 512x768.
+
+
Because each dot is spread over two actual pixels, the
+ display will be darker than in a normal video mode.
+
+
Any bitmap data will obviously need converting to the
+ correct 12 bit format: regular 15 or 16 bit images won't
+ display correctly...
+
+
Although this works like a truecolor mode, it is
+ actually using a 256 color palette, so palette fades are
+ still possible!
+
+
This code only works in linear screen modes (don't try
+ Mode-X).
+ This program demonstrates how to use an offscreen part of
+ the video memory to store source graphics for a hardware
+ accelerated graphics driver. The example loads the `mysha.pcx'
+ file and then blits it several times on the screen. Depending
+ on whether you have enough video memory and Allegro supports
+ the hardware acceleration features of your card, your success
+ running this example may be none at all, sluggish performance
+ due to software emulation, or flicker free smooth hardware
+ accelerated animation.
+
+
+
+ This program demonstrates the use of spline curves to create smooth
+ paths connecting a number of node points. This can be useful for
+ constructing realistic motion and animations.
+
+
+ The technique is to connect the series of guide points p1..p(n) with
+ spline curves from p1-p2, p2-p3, etc. Each spline must pass though
+ both of its guide points, so they must be used as the first and fourth
+ of the spline control points. The fun bit is coming up with sensible
+ values for the second and third spline control points, such that the
+ spline segments will have equal gradients where they meet. I came
+ up with the following solution:
+
+
+ For each guide point p(n), calculate the desired tangent to the curve
+ at that point. I took this to be the vector p(n-1) -> p(n+1), which
+ can easily be calculated with the inverse tangent function, and gives
+ decent looking results. One implication of this is that two dummy
+ guide points are needed at each end of the curve, which are used in
+ the tangent calculations but not connected to the set of splines.
+
+
+ Having got these tangents, it becomes fairly easy to calculate the
+ spline control points. For a spline between guide points p(a) and
+ p(b), the second control point should lie along the positive tangent
+ from p(a), and the third control point should lie along the negative
+ tangent from p(b). How far they are placed along these tangents
+ controls the shape of the curve: I found that applying a 'curviness'
+ scaling factor to the distance between p(a) and p(b) works well.
+
+
+ One thing to note about splines is that the generated points are
+ not all equidistant. Instead they tend to bunch up nearer to the
+ ends of the spline, which means you will need to apply some fudges
+ to get an object to move at a constant speed. On the other hand,
+ in situations where the curve has a noticable change of direction
+ at each guide point, the effect can be quite nice because it makes
+ the object slow down for the curve.
+
+
+
+ This program demonstrates how to support double buffering,
+ page flipping, and triple buffering as options within a single
+ program, and how to make things run at a constant rate no
+ matter what the speed of your computer. You have to use this
+ example from the commandline to specify as first parameter a
+ number which represents the type of video update you want: 1
+ for double buffering with memory bitmaps, 2 for page flipping,
+ 3 for triple buffering and 4 for double buffering with system
+ bitmaps. After this, a dialog allows you to select a screen
+ resolution and finally you will see a kaleidoscopic animation,
+ along with a frames per second counter on the top left of
+ the screen.
+
+
+
+ This program shows how to control the console switching mode, and
+ let your program run in the background. These functions don't apply
+ to every platform and driver, for example you can't control the
+ switching mode from a DOS program.
+
+
+ Yes, I know the fractal drawing is very slow: that's the point!
+ This is so you can easily check whether it goes on working in the
+ background after you switch away from the app.
+
+
+ Depending on the type of selected switching mode, you will see
+ whether the contents of the screen are preserved or not.
+
+
+
+ This program shows how to use the audio stream functions to
+ transfer large blocks of sample data to the soundcard. In
+ this case, the sample data is generated during runtime,
+ and the resulting sound reminds of a car engine when you
+ are accelerating.
+
+
+
+ This program demonstrates the use of the packfile functions, with some
+ simple tests.
+
+
+ The first test uses the standard packfile functions to transfer a
+ bitmap file into a block of memory, then reads the bitmap out of the
+ block of memory, using a custom packfile vtable.
+
+
+ The second test reads in a bitmap with another custom packfile
+ vtable, which uses libc's filestream functions.
+
+
+ The third test demonstrates seeking with a custom vtable.
+
+
+ The fourth test reads two bitmaps, and dumps them back into a
+ single file, using a custom vtable again.
+
+
+
+
+
+Allegro was originally created by Shawn Hargreaves. Published sometime between
+1994 and 1995, it was just a simple lib for himself. At that time, many people
+were switching from Borland C to DJGPP and looking for a decent graphics
+library. Allegro was the first reasonably complete one to show up, so it
+attracted enough interest to keep growing, and a little contribution here, and
+some more encouragement there made it all light up like fire.
+
+
+Some time after the latest 3.x stable release, though, Shawn was flooded with
+Allegro tasks and Real Life (TM) work, and chose the latter to focus his
+energies on. While this somehow stalled Allegro's development, it also
+attracted a lot of people who wanted Allegro to live longer. Also, by that
+time other people had started to work on Windows and Unix ports of Allegro,
+which suggested that Allegro had the potential to survive its only decaying
+main platform (DOS).
+
+
+The current situation is that Shawn still keeps watching Allegro's progress
+from time to time, but is not involved with development any more. The
+community that grew over the years when Shawn was in charge of everything has
+stepped forward to continue improving Allegro. Transformed into a meritocratic
+community, users keep sending bug reports to the mailing lists, developers
+around the world keep sending patches to fix them, and a few carefully chosen
+have write access to the CVS repository, from which releases are built every
+now and then.
+
+
+But, who decides when a build is stable enough? Who decides when somebody is
+granted write access to the CVS? Who chooses the lesser of two evils patching
+some obscure bug? And more importantly, who decides what's Allegro's mascot?
+For all these reasons, the community decided to replace Shawn's position with
+the Allegro Dictator.
+
+
+In republican Rome, political power was with the Senate and the Consuls.
+However, if it was nescessary that decisions were made very quickly then the
+senate could appoint a Dictator. The Dictator was appointed for a specified
+duration or charged with a specific task, after which he was expected to
+surrender his authority back to the Senate. Nowadays, the Allegro Dictator is
+a benevolent figure and rarely has to use his overwhelming fist of iron to put
+order into chaos.
+
+
+The truth is that the Allegro Dictator is usually the person in charge of
+doing releases and all that unsexy work inside the community, like pestering
+users to test some obscure bugfix or rejecting incomplete patches.
+
+
+Past Allegro dictators have been: Shawn Hargreaves, George Foot, Peter Wang
+and Eric Botcazou. At the moment of writing this, Evert Glebbeek is the
+active Allegro Dictator. Should you want to change Allegro in some illogical
+way, he's the guy you have to send your bribes too :-)
+
+
+
+
+All good things must come to an end. Writing documentation is not a good
+thing, though, and that means it goes on for ever. There is always something
+we've forgotten to explain, or some essential detail we've left out, but for
+now you will have to make do with this. Feel free to ask if you can't figure
+something out.
+
+
+Enjoy. We hope you find some of this stuff useful.
+
+
+
+By Shawn Hargreaves and the Allegro development team.
+
+
+ A
+ B
+ C
+ D
+ E
+ F
+ G
+ J
+ L
+ M
+ P
+ Q
+ R
+ S
+ T
+ V
+ Z
+ _
+ a
+ b
+ c
+ d
+ e
+ f
+ g
+ h
+ i
+ j
+ k
+ l
+ m
+ n
+ o
+ p
+ q
+ r
+ s
+ t
+ u
+ v
+ w
+ x
+
+
+ ______ ___ ___
+ /\ _ \ /\_ \ /\_ \
+ \ \ \L\ \\//\ \ \//\ \ __ __ _ __ ___
+ \ \ __ \ \ \ \ \ \ \ /'__`\ /'_ `\/\`'__\/ __`\
+ \ \ \/\ \ \_\ \_ \_\ \_/\ __//\ \L\ \ \ \//\ \L\ \
+ \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
+ \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
+ /\____/
+ \_/__/ Version 4.2.1
+
+
+ A game programming library.
+
+ By Shawn Hargreaves, Nov 26, 2006.
+
+ See the AUTHORS file for a
+ complete list of contributors.
+
+
+
+
+
+#include <std_disclaimer.h>
+
+ "I do not accept responsibility for any effects, adverse or otherwise,
+ that this code may have on you, your computer, your sanity, your dog,
+ and anything else that you can think of. Use it at your own risk."
+
+ Once Allegro 4.0 is released, we plan to maintain backward compatibility
+ at the Application Programming Interface level for the subsequent stable
+ releases of the 4.x series, that is for the releases with an even minor
+ version number. For example, that means you will be able to compile your
+ program written for version 4.0.0 with version 4.0.23 or version 4.2.1 of
+ the library. However, in order to fix some minor inconsistencies of the
+ original 4.0 API, we may make exceptions to the rule and break strict
+ backward compatibility in a few cases. But this is guaranteed to never
+ happen in a stable series for which major and minor version numbers are
+ fixed; in other words, two stable versions that differ from each other
+ only by the revision (3rd) number will be strictly backward compatible.
+
+
+ The 'aspect' parameter of get_camera_matrix() and get_camera_matrix_f()
+ strictly conforms to the documentation; in particular, setting it to 1
+ instructs the functions to do no scaling. This was not the case before,
+ because the functions multiplied this aspect ratio by 4/3.
+
+ Menus created from a DIALOG array (by using d_menu_proc for the proc pointer)
+ now correctly use the w and h fields as a minimum for their inclusive
+ dimensions (in the same way as all other GUI elements). Before, they would
+ draw the border outside of this dimension (1 pixel overdraw with other GUI
+ elements), and also add an additional 'shadow' to the right and the bottom
+ (2 pixels overdraw with other GUI elements).
+
+ The 'retrace_count' variable and the 'retrace_proc' callback function
+ take into account the refresh rate (if it is known) when the retrace
+ simulator is not installed. This was not the case before, except under
+ Windows.
+
+ The default value for the mouse configuration variable 'emulate_three'
+ has been changed to 'no' in all cases (even if you have a 2-button mouse).
+
+ The COLORCONV_KEEP_TRANS flag strictly conforms to the documentation now.
+ This was not the case before, because it was ignored when loading bitmaps
+ from datafiles. fixup_datafile() was modified to preserve transparency
+ when this flag is set, which was not guaranteed before in rare cases.
+
+ create_sub_bitmap() is now less tolerant about receiving bad arguments.
+ For example, it used to compensate for negative values for the origin
+ and return NULL if the parent bitmap was NULL. These cases are now
+ ASSERTed in the debug version, but unchecked in the release version.
+
+ install_allegro() and allegro_init() now return an error code if unable to
+ initialise a system driver. Previously they would have aborted the program
+ in such cases. Consequently you should check their return values.
+
+ The preprocessor symbol USE_CONSOLE is deprecated. Define instead the
+ symbol ALLEGRO_USE_CONSOLE prior to including Allegro headers in order
+ to set up Allegro for building a console application.
+
+ The constructors of the fix class from integer and floating point values
+ are now explicit.
+
+ All BeOS gfx driver IDs and constants have been replaced by more meaningful
+ ones. You may have to modify your allegro.cfg to reflect the change, or
+ update and recompile your programs if you used BeOS specific gfx drivers.
+
+ The behaviour of the GFX_SAFE driver has changed: it doesn't try to first
+ set up GFX_AUTODETECTed drivers anymore and is now guaranteed to be a
+ windowed driver when the platform has got a windowing system.
+
+ A datafile object returned by load_datafile_object() used not to contain
+ the properties attached to the object. This has been fixed.
+
+ object_message() now takes care of scaring and unscaring the mouse if the
+ message to be sent is MSG_DRAW.
+
+ file_select_ex() now treats '(+)d' as it does for any other attributes in
+ the extension string which is passed to it: only directories are included
+ and, among them, only those with the correct set of attributes.
+
+ d_ctext_proc() now behaves like d_text_proc() and d_rtext_proc(), that is
+ it takes into account the bounding box to calculate the position which the
+ string is centered around. It previously used only the x field. And, as a
+ consequence, gui_ctext_proc is now expected to behave the same.
+
+ dialog_message() now passes user messages to hidden objects.
+
+ set_volume() doesn't use the hardware mixer anymore to alter the global
+ volume. Use set_hardware_volume() instead to get the old behaviour.
+
+ The default sound volume of Allegro was raised, since there no longer is
+ the risk of wrapping with the new mixer. To restore the volume level to
+ that of previous versions, look at the set_volume_per_voice function.
+ Programs already using set_volume_per_voice are not affected.
+
+ The semantics of rest are clarified so rest(0) does yielding when
+ possible.
+
+ The get_align_matrix[_f] functions would return mirrored matrices in some
+ cases, this was fixed.
+
+ In many places 'unsigned long' variables were used to hold memory
+ addresses. These have been changed to use the 'uintptr_t' type instead.
+
+ 15-bit and 16-bit bitmaps used to be arrays of unsigned shorts, and 32-bit
+ bitmaps used to be arrays of unsigned longs. They have been changed to be
+ arrays of 16-bit and 32-bit integers respectively. This makes a difference
+ on platforms where an unsigned long is not 32-bits wide (e.g. some 64-bit
+ platforms).
+
+ The following items have been deprecated and the main documentation was
+ purged of any references to them. If you are still using any of those, now
+ might be a good time to get rid of them (within parentheses is the symbol
+ most likely to be a replacement for the obsolete one, if any). However
+ they are still supported for the sake of backwards compatibility, unless
+ you define the symbol ALLEGRO_NO_COMPATIBILITY prior to including Allegro
+ headers.
+
+
+
+ clear (clear_bitmap).
+
+ cpu_fpu (cpu_capabilities, in combination with CPU_FPU).
+
+ cpu_mmx (cpu_capabilities, in combination with CPU_MMX).
+
+ cpu_3dnow (cpu_capabilities, in combination with CPU_3DNOW).
+
+ cpu_cpuid (cpu_capabilities, in combination with CPU_ID).
+
+ draw_character (draw_character_ex, passing the mode you would have passed
+ to text_mode() as the 'bg' parameter).
+
+ fadd (fixadd).
+
+ fsub (fixsub).
+
+ fmul (fixmul).
+
+ fdiv (fixdiv).
+
+ fceil (fixceil).
+
+ ffloor (fixfloor).
+
+ fcos (fixcos).
+
+ fsin (fixsin).
+
+ ftan (fixtan).
+
+ facos (fixacos).
+
+ fasin (fixasin).
+
+ fatan (fixatan).
+
+ fatan2 (fixatan2).
+
+ fsqrt (fixsqrt).
+
+ fhypot (fixhypot).
+
+ file_size (file_size_ex)
+
+ file_select (file_select_ex, passing the two constants OLD_FILESEL_WIDTH
+ and OLD_FILESEL_HEIGHT if you want the file selector to be displayed with
+ the dimensions of the old file selector).
+
+ fix_filename_path (canonicalize_filename).
+
+ for_each_file (for_each_file_ex).
+
+ gui_textout (gui_textout_ex, passing the mode you would have passed to
+ text_mode() as the 'bg' parameter).
+
+ Status: it works. It currently doesn't build the Allegro library
+ from the sources, but it does let you compile your own Allegro-based
+ programs and run them with the Allegro DLLs. Thanks to Inprise for
+ creating the very useful IMPLIB program.
+
+
+ The screensaver example is built, but you must copy scrsave.scr to
+ your windows/system directory (or winnt/system32 directory
+ under Windows NT/2k/XP) if you want to test it.
+
+
+
+
Borland C++Builder (or Borland C++ command line tools)
+
Recent set of DirectX and other Windows SDK headers.
+
GNU make 3.77 or higher.
+
Optional: GNU sed. Used by "make depend" and "fixdll.bat".
+
Optional: GNU sort (not DOS sort). Used by "fixdll.bat".
+
+ In order to run your programs, you need to obtain the Allegro DLLs and
+ install them in the Windows system directory.
+
+
+ This is known to work with the Borland C++ 5.5 command line compiler.
+ Earlier versions may cause problems (for example v5.02).
+
+
+ You need to use GNU make, since Borland make is really ugly about its
+ makefiles. You can grab it from either the MinGW or DJGPP
+ distributions; more info on this in available in the following files:
+ docs/build/mingw32.txt and docs/build/djgpp.txt.
+
+
+
+
+ Set up your environment so that Borland C++ can be used from the
+ commandline. Then set the variable BCC32DIR to the directory where
+ Borland C++ is located, for example 'set BCC32DIR=c:\bcc32'.
+
+
+ Type "cd allegro" and then "fix.bat bcc32". Then, run "make". Find
+ something fun to do while it's compiling. It will eventually
+ finish; then just type "make install" to set the library up for use.
+
+
+ If you also want to install a debugging version of the library (highly
+ recommended), type "make install DEBUGMODE=1". Case is important, so
+ it must be DEBUGMODE, not debugmode!
+
+
+ If you also want to install a profiling version of the library, now type
+ "make install PROFILEMODE=1".
+
+
+ If your copy of Allegro doesn't include the makefile.dep dependency files
+ (unlikely, unless you have run "make veryclean" at some point), you can
+ regenerate them by running "make depend".
+
+
+ If your copy of Allegro doesn't include the linker .def file (unlikely,
+ unless you have run "make veryclean" at some point), you can regenerate
+ it by running "misc\fixdll.bat".
+
+
+
+
+ All the Allegro functions, variables, and data structures are defined in
+ allegro.h. You should include this in your programs, and link with one of
+ the libraries:
+
+ Don't forget that you need to use the END_OF_MAIN() macro right after
+ your main() function!
+
+
+ You will need to distribute the appropriate DLL along with your program.
+
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/build/beos.html b/lib/allegro/allegro-htmldocs-4.2.1/build/beos.html
new file mode 100644
index 0000000..8dcbbf9
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/build/beos.html
@@ -0,0 +1,146 @@
+
+
+ BeOS Intel R4 and R5 Pro Edition come with everything you need. If you
+ have BeOS Intel R5 Personal Edition, you require the development tools;
+ these can be found on the Be homepage at http://www.be.com. You also need
+ updated binutils, which can be found at http://bebits.com. It might not
+ be a bad idea to update gcc as well, but is not required.
+
+
+
+
+ Allegro comes as a source distribuition: you'll have to compile it to get
+ it to work. Unzip the library archive wherever you want, and cd into that
+ directory with a Terminal. Due to the multi-platform nature of Allegro,
+ you need to run:
+
+ fix.sh beos
+
+ This will set the library ready to be compiled on the Be platform.
+ Now you must build it:
+
+ make
+
+ And then install it:
+
+ make install
+
+ With this last command the Allegro library will be installed into
+ /boot/home/config/lib (the default location for BeOS shared libraries),
+ while the headers will go into /boot/develop/headers (the default
+ locations where Be looks for them).
+
+
+ You have now installed Allegro! See the rest of the documentation and
+ examples to learn more about it. A simple example of a command line to
+ compile an allegro program:
+
+ The `allegro-config --shared` is explained in the next section.
+
+
+ The dynamically linked version of Allegro gets built by default but if
+ you want to build the statically linked version of Allegro write the
+ following on the command line:
+
+ export STATICLINK=1
+
+ In the same manner we can also enter one of the following lines to
+ build either the debug or the profiling version of the library:
+
+ export DEBUGMODE=1
+ export PROFILEMODE=1
+
+ Then we can start to actually make and install the Allegro library.
+
+ make
+ make install
+
+ If you have compiled a static version of the library, it will be copied to
+ /boot/develop/lib/x86.
+
+
+
+
+ Linking Allegro to a program also requires you to link several other BeOS
+ libraries and set the correct library search pathes. To simplify the
+ linking process, the installation sets up a script, allegro-config, that
+ will print out a suitable commandline. You can use this inside backtick
+ command substitution, for example:
+
+ This will enable you to link against the static library.
+
+
+ The `allegro-config --shared` option mentioned above will output all the
+ options and libraries needed to link dynamically against the shared
+ version of the Allegro library. If you use --libs instead of --shared or
+ --static, the script will generate the linking arguments according to the
+ latest installed library version. You can also run these allegro-config
+ commands on the commandline to see what exactly they do.
+
+
+ If you want to build a debug version of your program, assuming that
+ you have installed the debug version of Allegro, use:
+
+ Terminal newbies, take note that these are ` backticks, not normal '
+ quotes!
+
+
+ There are also other switches for printing out the Allegro version number,
+ or to override the install paths. Run allegro-config without any
+ arguments for a full list of options.
+
+
+ Don't forget that you need to use the END_OF_MAIN() macro right after
+ your main() function!
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/build/darwin.html b/lib/allegro/allegro-htmldocs-4.2.1/build/darwin.html
new file mode 100644
index 0000000..7224846
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/build/darwin.html
@@ -0,0 +1,143 @@
+
+
+Notes on building the Darwin/X11 version of Allegro
+
+
+
+
+
+ ______ ___ ___
+ /\ _ \ /\_ \ /\_ \
+ \ \ \L\ \\//\ \ \//\ \ __ __ _ __ ___
+ \ \ __ \ \ \ \ \ \ \ /'__`\ /'_ `\/\`'__\/ __`\
+ \ \ \/\ \ \_\ \_ \_\ \_/\ __//\ \L\ \ \ \//\ \L\ \
+ \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
+ \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
+ /\____/
+ \_/__/
+
+ Notes on building the Darwin/X11 version of Allegro.
+
+ Written by Jeremiah Blanchard.
+
+ See docs/build/unix.txt for general Unix information.
+
+ See readme.txt for a more general overview.
+
+ If you are running MacOS X, you must download the developer tools. This
+ requires free registration with Apple. You can register and download the
+ tools at:
+
+ Recently, GCC 3.1 has been released which supports the Mach-O binary
+ format, and you may be able to use it directly (if you compile it
+ yourself or find a binary distribution.)
+
+
+ You will also need X Window. You can use either the Darwin/MacOS X port
+ of XFree86 from the XonX project or Xtools, a proprietary version. The
+ XonX project is located at:
+
+ First, decompress the .tar or .zip file into some directory. Next, open
+ up a terminal (in MacOS X, this can be found in Applications/Utilities).
+ From here, enter the directory into which Allegro has been decompressed.
+
+
+ If you are using the .zip file, type the following:
+
+ chmod +x fix.sh
+ ./fix.sh unix
+
+ From here on everything is a pretty standard Unix-style install process.
+ First you configure it with at least the following options:
+
+ If you are using an older version of Apple's tools, you will probably see
+ lots of preprocessing errors. Just ignore them (they are due to Apple's
+ modifications to GCC and do not affect the resulting object code).
+
+
+ To install Allegro, you will need root permissions. If you don't have
+ root permissions set up on your system (in MacOS X, for example), you
+ will first need to activate the root account. This can be done by running
+ the program "NetInfo Manager" in Applications/Utilites. From within the
+ program, go to the "Domain" menu, select "Security" and "Authenticate".
+ Type in your password and go to "Domain", "Security", "Root User Enable".
+ I strongly urge you to set your root password in the same menu.
+
+
+ Now, type the following in the terminal:
+
+ su -c "make install"
+
+ To install the man pages, type:
+
+ su -c "make install-man"
+
+ If prompted for a password, type in your root password.
+
+
+
+
+ Status: complete. This is the original Allegro version, and has had
+ plenty of time to become nice and stable. However, under Windows NT,
+ 2000, or XP you will very likely experience problems and should consider
+ using the native Windows version of Allegro instead, less likely to give
+ you problems under such environments.
+
+
+
+
GCC compiler 2.91.x or later (gcc*b.zip).
+ Note: gcc 3.0.x (0 <;= x <;= 1) doesn't properly compile Allegro.
+
Binutils 2.9.x or later (bnu*b.zip).
+
GNU make (mak*b.zip).
+
Texinfo (txi*b.zip).
+
Optional: sed (sed*b.zip). Used by "make depend".
+
+ All of the above can be downloaded from your nearest SimTel mirror site,
+ in the /pub/simtelnet/gnu/djgpp/ directory, or you can use the zip picker
+ on http://www.delorie.com/djgpp/. Please make sure that you have
+ installed djgpp according to the instructions in readme.1st, and that you
+ aren't mixing it with any files from different compilers (eg. the Borland
+ version of make).
+
+
+
+
+ If you are using a CVS version of Allegro, then you will need to do some
+ extra things to ensure that your copy of Allegro will compile correctly.
+ These are covered in detail below, but briefly:
+
+
+ 1. You must run the `fix' script (either the batch file, under
+ command.com, or the .sh file under bash). You must supply the
+ argument `djgpp'.
+
+
+ 2. You must regenerate the dependency files: a simple `make depend'
+ will do this. However, please note that you must have sed installed
+ to do this.
+
+ This is a source-only distribution, so you will have to compile Allegro
+ before you can use it. To do this you should:
+
+
+ Go to wherever you want to put your copy of Allegro (your main djgpp
+ directory would be fine, but you can put it somewhere else if you
+ prefer), and unzip everything. Allegro contains several subdirectories,
+ so you must specify the -d flag if you are using pkunzip.
+
+
+ If you are running under Linux, and want to cross-compile the djgpp
+ version of Allegro, set the environment variable "CROSSCOMPILE=1", set
+ DJDIR to the directory where your djgpp cross-compiler is installed,
+ set PATH to access to the cross-compiler, and set NATIVEPATH to a path
+ that will use your native version of gcc instead (_not_ the djgpp
+ cross-compiler!) so that this can be invoked when converting the
+ documentation. You might like to edit and use `xmake.sh'; there are
+ further instructions in comments in the file. You must also run
+ 'fix.sh djgpp' as detailed above - it is required to properly configure
+ Allegro for building with djgpp.
+
+
+ Type "cd allegro", followed by "make". Then go do something interesting
+ while everything compiles. When it finishes compiling, type "make
+ install" to set the library up ready for use. If you have any trouble
+ with the build, look at docs/txt/faq.txt for the solutions to some of the
+ more common problems.
+
+
+ If you also want to install a debugging version of the library (highly
+ recommended), now type "make install DEBUGMODE=1". Case is important, so
+ it must be DEBUGMODE, not debugmode!
+
+
+ If you also want to install a profiling version of the library, now type
+ "make install PROFILEMODE=1".
+
+
+ If you want to read the Allegro documentation with the Rhide online help
+ system, go to the "Help / Syntax help / Files to search" menu, and add
+ "allegro" after the existing "libc" entry (separated by a space).
+
+
+ If you want to create the HTML documentation as one large allegro.html
+ file rather than splitting it into sections, edit docs/allegro._tx,
+ remove the @multiplefiles statement from line 8, and run make again.
+
+
+ Once the build is finished you can recover some disk space by running
+ "make compress" (which uses the DJP or UPX programs to compress the
+ executable files), and/or "make clean" (to get rid of all the temporary
+ files and HTML format documentation).
+
+
+ If your copy of Allegro is set up for use with some different compiler
+ (if you downloaded a tar.gz archive or a CVS version), you will have to
+ run 'fix.bat djgpp' before compiling it. If you are using bash you can run
+ 'fix.sh djgpp' instead.
+
+
+ If your copy of Allegro doesn't include the makefile.dep dependency files
+ (if you have run "make veryclean" or you have the CVS version), you can
+ regenerate them by running "make depend".
+
+
+ Set this if you are crosscompiling; it implies UNIX_TOOLS.
+
+
+
WARNMODE
+ Set this if you want Allegro to display and stop on nearly all
+ warnings issued by the compiler. Allegro should compile fine with
+ this set.
+
+
+
TARGET_ARCH_COMPAT
+ or
+ TARGET_ARCH_EXCL
+ These affect the level of processor dependant optimisation that
+ Allegro uses. You can set either of these to the processor type you
+ want to optimize for. The difference between these two is that
+ TARGET_ARCH_COMPAT optimise for the given processor so that the code
+ will still run on older processors, while TARGET_ARCH_EXCL will
+ generate code that will run exclusively on the given processor and of
+ course newer ones. Example: set TARGET_ARCH_COMPAT=i686
+
+
+
TARGET_OPTS
+ Affects the general optimisations that Allegro uses.
+
+
+
UNIX_TOOLS
+ If your system does not have the usual DOS tools available (`md',
+ `rd', `copy', etc., and commands which understand the \ character),
+ then set this to 1 to use the Unix equivalents. This is set
+ implicitly when you set CROSSCOMPILE, and is also set automatically
+ when you are running under bash.
+
+
+ To activate any of these, type (for example) "make WARNMODE=1".
+
+
+
+
+ All the Allegro functions, variables, and data structures are defined in
+ allegro.h. You should include this in your programs, and link with either
+ the optimised library liballeg.a, the debugging library liballd.a, or the
+ profiling library liballp.a. To do this you should:
+
+
+ Put the following line at the beginning of all C or C++ files that use
+ Allegro:
+
+ #include <allegro.h>
+
+ If you compile from the command line or with a makefile, add either
+ '-lalleg' (for the optimised version), '-lalld' (debugging version), or
+ '-lallp' (profiling version) to the end of the gcc command, eg:
+
+ gcc foo.c -o foo.exe -lalleg
+
+ If you are using Rhide, go to the Options/Libraries menu, type either
+ 'alleg' (for the optimised version), 'alld' (debugging version), or
+ 'allp' (profiling version) into the first empty space, and make sure the
+ box next to it is checked.
+
+
+
+
+ The bare minimum you need to use Allegro is a 386 with a VGA graphics
+ card, but a 486 is strongly recommended. To get into SVGA modes you will
+ need a compatible SVGA card, which means something that has a working
+ VESA or VBE/AF driver.
+
+
+ Ideally you should use VBE/AF, because it allows Allegro to use hardware
+ acceleration functions to speed up the drawing. The FreeBE/AF project
+ (http://www.talula.demon.co.uk/freebe/) provides a number of free VBE/AF
+ drivers (volunteers to write more are always welcome!), and accelerated
+ drivers for a large number of cards are available commercially as part of
+ the SciTech Display Doctor package (http://www.scitechsoft.com/).
+
+
+ If you have a VBE 2.0 or VBE 3.0 driver you are probably fine just using
+ that, although unlike VBE/AF it won't provide any hardware acceleration.
+ If you have an older VESA BIOS implementation (eg. VESA 1.2), beware. For
+ one thing, everything will be much slower if Allegro can't use the sexy
+ VBE 2.0 features. For another, I could go on all day telling horror
+ stories about the buggy and generally just pathetic VESA implementations
+ that I've come across. If you are having trouble with the SVGA modes, try
+ getting a copy of the SciTech Display Doctor and see if that clears
+ things up (it probably will: SciTech usually get these things right).
+
+
+ Note that the native SVGA chipset drivers from Allegro 3.0 and earlier
+ have been removed. These are still available as an optional add-on
+ package from the same sites as Allegro, but are not needed any more
+ because you can get the same code in a more flexible format as part of
+ the FreeBE/AF project.
+
+
+ On the sound front, Allegro supports sample playback on the SB (mono),
+ the SB Pro (stereo), the SB16, the ESS AudioDrive, the Ensoniq
+ Soundscape, and the Windows Sound System. It has MIDI drivers for the
+ OPL2 FM synth (Adlib and SB cards), the OPL3 (Adlib Gold, SB Pro-II and
+ above), the pair of OPL2 chips found in the SB Pro-I, the AWE32 EMU8000
+ chip, the raw SB MIDI output, and the MPU-401 interface, plus it can
+ emulate a wavetable MIDI synth in software, running on top of any of the
+ supported digital soundcards. The Creative Labs SB PCI-64 and PCI-128
+ cards are actually based on the Ensoniq chipset, so they can be used with
+ the Soundscape and MPU-401 drivers. You'll have to manually select the
+ MPU, though, because it won't be autodetected. Actually, quite a lot of
+ wavetable boards emulate the MPU, so give this a try and see if it works
+ on your card. If you feel like coming up with drivers for any other
+ hardware, they would be much appreciated.
+
+
+ Audio recording is supported for all SB cards, but only in unidirectional
+ mode, ie. you cannot simultaneously record and playback samples. MIDI
+ input is provided by the MPU-401 and SB MIDI drivers, but there are some
+ restrictions on this. The SB MIDI interface cannot be used at the same
+ time as the digital sound system, and the MPU will only work when there
+ is an IRQ free for it to use (this will be true if you have an SB16 or
+ greater, or if no SB-type digital driver is installed, or if your MIDI
+ interface uses a different IRQ to the SB).
+
+
+
+
+ The OPL2 synth chip can provide either nine voice polyphony or six voices
+ plus five drum channels. How to make music sound good on the OPL2 is left
+ as an exercise for the reader :-) On an SB Pro or above you will have
+ eighteen voices, or fifteen plus drums. Allegro decides whether to use
+ drum mode individually for each MIDI file you play, based on whether it
+ contains any drum sounds or not. If you have an orchestral piece with
+ just the odd cymbal crash, you might be better removing the drums
+ altogether as that will let Allegro use the non-drum mode and give you an
+ extra three notes polyphony.
+
+
+ When Allegro is playing a MIDI file in looped mode, it jumps back to the
+ start of the file when it reaches the end of the piece. To control the
+ exact loop point, you may need to insert a dummy marker event such as a
+ controller message on an unused channel.
+
+
+ All the OPL chips have very limited stereo capabilities. On an OPL2,
+ everything is of course played in mono. On the SB Pro-I, sounds can only
+ be panned hard left or right. With the OPL3 chip in the SB Pro-II and
+ above, they can be panned left, right, or centre. I could use two voices
+ per note to provide more flexible panning, but that would reduce the
+ available polyphony and I don't want to do that. So don't try to move
+ sounds around the stereo image with streams of pan controller messages,
+ because they will jerk horribly. It is also worth thinking out the
+ panning of each channel so that the music will sound ok on both SB Pro-I
+ and OPL3 cards. If you want a sound panned left or right, use a pan value
+ less than 48 or greater than 80. If you want it centred, use a pan value
+ between 48 and 80, but put it slightly to one side of the exactly central
+ 64 to control which speaker will be used if the central panning isn't
+ possible.
+
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/build/linux.html b/lib/allegro/allegro-htmldocs-4.2.1/build/linux.html
new file mode 100644
index 0000000..de3bf3e
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/build/linux.html
@@ -0,0 +1,204 @@
+
+
+ On Linux you have two different system drivers -- one for running using
+ X, and one for running without X. For information on the X version, and
+ instructions telling how to install Allegro and compile your programs on
+ a Unix system, see docs/build/unix.txt. This file only describes the
+ Linux console routines.
+
+
+ Normally the X version is used in preference to the console version, if
+ an X server is contactable (this means that your programs will use X if
+ you launch them from inside X, and otherwise use the console). You can
+ change this using your config file if you like, or by configuring
+ --without-x.
+
+
+
+
+ Some parts of Linux console Allegro need root privileges. Others don't.
+ Specifically, the VGA, mode-X and VBE/AF graphics drivers do. The fbcon
+ driver doesn't. Also, if you intend to run a program from something which
+ isn't a VT (e.g. an xterm (but not using the X version), a remote login,
+ a screen session) then you need to either own a (free) console numbered
+ from 1 to 15 or to have root privileges.
+
+
+ If you want a program to run with privileges even though the user running
+ it is not root, make root own the binary and set the suid bit:
+
+ That makes the executable be owned by root and group `allegro'. It's
+ readable, writable and executable by root and people in that group. Also,
+ when it runs, it has root privileges. For that reason, it's not
+ executable by the general public. Put trusted users into group `allegro'.
+
+
+ You might prefer to use `4750' instead of `4770' -- then people in the
+ group cannot write to the binary.
+
+
+ Allegro will drop the privileges almost immediately after initialisation,
+ using `seteuid'. This means that you can still get the permissions back
+ later on. Allegro needs to be able to regain the privileges if you intend
+ to call `allegro_init' again in the future. If this isn't the case, you
+ can completely give up the privileges using `setuid(getuid());' -- then
+ they are lost for good.
+
+
+ Security note: If you don't do this, any buffer overflows are a severe
+ security problem. In any case, you should take great care when allowing
+ random people to execute third-party programs suid root.
+
+
+ If, as root, you run `make suid', it will do this to all of the programs
+ generated -- the demo game, the examples, the tests, etc.
+
+
+
+
+ This section contains Linux-specific notes on the drivers available.
+
+
+
System:
+ On initialisation, Allegro will try to get a certain amount of
+ control over the console. This doesn't generally require root
+ privileges, but if the program isn't being run from a plain VC (e.g.
+ it's running from within X or screen), Allegro must try to allocate
+ a spare VC and move the program to it. This requires a free console
+ we can read from and write to; unless the user has allocated some,
+ we need to be root here.
+
+
+ Display switching is possible; all of Allegro's modes are supported.
+ The default is SWITCH_PAUSE. SWITCH_BACKGROUND will only work if the
+ application takes special precautions.
+
+
+
Graphics:
+ Linux Allegro supports standard VGA and mode-X by direct writes to
+ the video card. You need root privileges for this to work.
+
+
+ It also supports fbcon, for which you do not need privileges, but
+ you do need a recent kernel, correctly configured.
+
+
+ The VBE/AF system does require root privileges. Note it is not built by
+ default and hasn't been tested in a long time. Basically, you should
+ not bother with it. But if you insist, you need to get a VBE/AF driver
+ that works in Linux -- the FreeBE/AF project has two at present, but
+ the project itself hasn't been ported to Linux. You can just copy out
+ the driver binaries, though. Put the appropriate driver into
+ `/usr/local/lib', `/usr/lib', `/lib' or
+ `/', filename `vbeaf.drv' -- or put it anywhere you
+ like, specifying the location in the config file as for the DOS
+ version.
+
+
+ For security reasons, the VBE/AF driver binary must be owned by root
+ and only writable by root. You really don't want to load and execute
+ user-specified binary code in a privileged program.
+
+
+ The SVGAlib driver should be fairly stable and fast now, and can use
+ most of the video modes that SVGAlib provides. It requires root
+ privileges if your version of SVGAlib requires them.
+
+
+
Sound:
+ The ALSA drivers support both the older 0.5.x version of the ALSA API
+ as well as the newer 0.9.x+ series. Support for the older API will be
+ dropped later.
+
+
+
Keyboard:
+ The keyboard driver uses the kernel mapping tables to map scancodes
+ to character codes and key functions, so your keyboard mapping
+ should be fine without special configuration in the setup program.
+
+
+
Joystick:
+ To compile Allegro with joystick support you must have a 2.2.* or newer
+ kernel, i.e. with kernel-based joystick support. Look for
+ /usr/src/linux/include/linux/joystick.h. You shouldn't have to
+ actually configure the kernel with joystick support though, you just
+ need that header file.
+
+
+ Similarly, to run Allegro programs with joystick support you must have
+ configured joystick support into the kernel. You also need to create
+ the device file /dev/input/js0, if it's not already there.
+
+
+ See /usr/src/linux/Documentation/joystick.txt for details.
+
+
+
Mouse:
+ Currently Linux Allegro supports PS/2 and Microsoft mice directly,
+ and other mouse types via GPM. To use GPM you must turn on its
+ `repeater' feature, where it copies all mouse activity to the FIFO
+ /dev/gpmdata. Edit your init scripts and add the `-R' option. The
+ GPM driver can also be used with native Mouse Systems mice by
+ changing the `mouse_device' variable in the config file.
+
+
+ When using the PS/2 Intellimouse protocol, it is necessary to
+ explicitly put the mouse into wheel mode, which requires Allegro
+ to have write permissions to the device.
+
+
+ There is now also a input events-based driver which reads events from
+ /dev/input/eventN.
+ On the same page you will also find instructions on how to install them.
+ Note that system version 10.2.x is required to compile Allegro, but
+ the library will still work on 10.1.x.
+
+
+
+
+ Allegro ships in source code form; this means you need to compile it
+ before you can use it. You do this easily from a terminal window.
+ Due to the multiplatform nature of the library, the first step is to
+ fix it so it can be built under MacOS X, by running:
+
+ chmod +x fix.sh
+ ./fix.sh macosx
+
+ If you have checked out a development version from Allegro's CVS
+ repository, run the following command. Otherwise, skip this step:
+
+ make depend
+
+ Now Allegro is ready to be compiled. Start building it:
+
+ make
+
+ And finally you install it (you need the root password for this step):
+
+ sudo make install
+
+ Allegro has now been installed in your system as a standalone shared
+ library, in /usr/local/lib.
+ You may also wish to install the man pages:
+
+ sudo make install-man
+
+ Alternatively, you can view the documentation in the Mac Help Center:
+
+ sudo make install-applehelp
+
+ You may also wish to install the library as a standard MacOS X framework:
+
+ sudo make install-framework
+
+ The "Allegro" framework will be created into /Library/Frameworks. Note
+ that the framework is standalone: it contains its own copy of the
+ dynamic library, so it can be safely copied around.
+ If you plan to embed the Allegro framework inside your application
+ bundles, you must install a special embeddable version of it:
+
+ sudo make install-framework EMBED=1
+
+ Embedding the framework into your application bundles ensures they will
+ work also on machines where Allegro is not installed. Note that if you
+ embed the non-embeddable version of the framework into your app bundle,
+ your program will not be able to load it and it will not work.
+ Finally, if you plan on using Project Builder to code your apps, you
+ may find useful installing an Allegro application PB project template:
+
+ sudo make install-template
+
+ The dynamically linked version of the library gets built by default, but
+ if you want to build a statically linked one, write the following on the
+ command line:
+
+ export STATICLINK=1
+
+ In the same manner we can also enter one of the following lines to
+ build either the debug or the profiling version of the library:
+
+ export DEBUGMODE=1
+ export PROFILEMODE=1
+
+ Then restart the build process by issuing:
+
+ make
+ sudo make install
+
+ The static library will be installed in /usr/local/lib as the shared one,
+ but you will not be able to install the framework nor the Project Builder
+ template, which require a dynamically linked Allegro version.
+
+
+ If you have OS X 10.4 and you want to build a Universal Binary version of the library
+ (i.e. one that will run on both PowerPC and Intel Macs) you can type
+
+ ./fix.sh macosx-universal
+
+ instead of the fix.sh line given above. Note that you'll still need to specify
+ the appropriate flags when you link your program, otherwise gcc will 'thin' the binary
+ so it only includes the native code.
+
+
+ For more information see
+ http://developer.apple.com/documentation/MacOSX/Conceptual/universal_binary/
+
+
+
+ The options for linking with Allegro are quite long, expecially for
+ static versions of the library as you need to pull in several different
+ frameworks (Cocoa, QuickTime, etc.) other than Allegro itself. When
+ linking against the shared library version, things are also different.
+ To avoid you having to work out the right linker commands for yourself,
+ the installation creates a script, allegro-config, that will print out a
+ suitable commandline. You can use this inside a backtick command
+ substitution, for example:
+
+ Unix newbies, take note that these are ` backticks, not normal ' quotes!
+
+
+ There are also switches for printing out the Allegro version number,
+ overriding the install paths, and selecting between shared and static
+ libraries, in case you installed both. Run allegro-config without any
+ arguments for a full list of options.
+
+
+ If you get an error like 'allegro-config: program not found', and
+ you're sure you have built and installed the library as described above, it
+ probably means that /usr/local/bin is not on your path. The method
+ to add it depends on the shell you're using. If you have tcsh, add the
+ following line to the end of the .cshrc in your home directory.
+
+ set path=($path /usr/local/bin)
+
+ If you have bash, add the following line to the end of the .bash_profile
+ file in your home directory:
+
+ PATH=${PATH}:/usr/local/bin
+
+ If you don't know which, just type echo $SHELL on the command
+ line, which will print either /bin/bash or /bin/tcsh.
+ Newer versions of OSX use bash, older ones use tcsh.
+ You will have to close the Terminal window and open a new one once
+ you have made the changes, so it will have an effect.
+
+
+ To use Allegro from inside Apple's Project Builder, be sure you first
+ installed the library as a framework and that you also installed the PB
+ application template (see section "Installing Allegro" for details).
+
+
+ Once you're ready, start up Project Builder and choose "New Project"
+ from the "File" menu. On the very first dialog, you'll be prompted
+ with a list of project templates with which to create your program.
+ Select "Allegro Application" under the "Application" category and enter
+ the project name and location in the next dialog. Once the setup is
+ complete, you will find yourself with an opened Allegro application
+ project, holding an unique source file (main.c) and some linked
+ frameworks. The project can already be compiled to a working application;
+ try it!
+
+
+ Note that the same procedure applies to XCode, which is compatible
+ with Project Builder.
+
+
+ The main.c source file contains a very simple skeleton of an Allegro
+ program that will open up a white window with the text "Hello, world!"
+ in the center. This file is just a start: you can (and should) completely
+ replace its contents to suit your needs.
+
+
+
+
+ When you build applications from the command line, you're actually just
+ creating the executable, so you can run it from the command line only,
+ and not also from the finder like a common MacOS X application. In other
+ words, compiling from the command line does not create application
+ bundles.
+
+
+ Allegro ships with a little tool, named fixbundle, which allows to build
+ an application bundle out of an executable.
+ The utility works from the command line and it accepts a variety of
+ options to customize your bundle; the easiest way to use it is:
+
+ fixbundle executable_name
+
+ This will create an application bundle named "executable_name.app" that
+ contains your program executable and will appear in the finder with the
+ default application icon. A more complex usage example follows:
+
+ This creates a bundle named "bundle_name.app". The executable will be
+ moved instead of copied into the bundle; the application will be marked
+ as version "1.2" and icon.bmp will be converted to an icon for the
+ bundle. You can specify more options and up to 4 differently sized
+ icons (16x16, 32x32, 48x48 and 128x128) to be read from any Allegro
+ supported image files or from datafile objects.
+ Run fixbundle without arguments for the full list of known options.
+
+
+ A special note is required for the "-e" switch; this lets you embed
+ the Allegro framework inside the built application bundle, so your
+ app will not require Allegro to be installed into the target machine
+ in order to work. This flag assumes you previously installed the
+ embeddable version of the Allegro framework, and that your executable
+ has been linked to it, either via Project Builder or XCode, either
+ via the allegro-config script.
+ If one of these conditions is not met, the created app may not
+ work on target machines.
+
+
+ Bundles created by fixbundle have this default layout:
+
+ If you are using Project Builder to compile your programs, there is no
+ need to use fixbundle, as the IDE will do the work of generating an
+ application bundle for you.
+
+
+ When an Allegro program starts, it automatically detects if the
+ executable lives inside a bundle or not. The working directory is
+ always set up to be the directory where the standalone executable
+ or application bundle is located, but there is an exception: if the
+ application is a bundle and Allegro finds a directory under the bundle
+ Contents/Resources path with the same name of the executable (note that
+ here we mean the real executable name, not the bundle name), that
+ directory is set to be the working one. This allows to easily package
+ all the application data inside the bundle, and still have a working
+ program without the need to tell your code about the changed location
+ of your files.
+
+
+
+
+ This section contains MacOS X-specific notes on the drivers available.
+
+
+
System:
+ When the system driver is about to be initialized, we already
+ have a working NSApplication object connected to the Window Server.
+ At driver startup, the working directory is changed if inside a
+ bundle with a proper data directory under the Contents/Resources
+ path (see above).
+
+
+ Display switching is possible, but only the SWITCH_BACKGROUND
+ mode is supported, so your application will have to deal with it.
+
+
+
Graphics:
+ The MacOS X windowed graphics mode uses a Cocoa window with a
+ Quartz QuickDraw view as its content view. All combinations of
+ window/desktop color depths are supported; if needed, color
+ conversion will automatically be done transparently to the user.
+
+
+ Fullscreen mode uses the CoreGraphics DirectDisplay API; only
+ 8, 15 and 32 bit color depths are supported.
+
+
+
Sound:
+ The CoreAudio digital/MIDI drivers use V2 AudioUnits, and thus
+ they require MacOS X 10.2.x (Jaguar) or newer to work. If this is
+ not the case, you can fall back to the Carbon Sound Manager and
+ Quicktime MIDI drivers.
+
+
+
Keyboard:
+ MacOS X Allegro uses the current system keyboard mapping table
+ to map scancodes to characters: the keyboard user settings in
+ allegro.cfg have no effect.
+
+
+
Mouse:
+ On MacOS X 10.2.x (Jaguar) or newer, Allegro will automatically
+ detect the number of buttons of your mouse at driver initialization.
+ If the 1-button Apple mouse is found, the library will activate an
+ emulation mode that mimics the way MacOS X itself deals with
+ 1-button mice: depending on which key is pressed when the button is
+ clicked, Allegro will report a different mouse button click.
+ (Control + button) emulates a right click and (Option + button)
+ emulates a middle click.
+
+
+ On MacOS X 10.1.x, mouse autodetection is not possible, and Allegro
+ will assume an 1-button mouse to always be present, activating
+ buttons emulation accordingly.
+ There is a known compatibility problem when using gcc 4 on MacOS X 10.4
+ that prevents binaries from working on older versions of MacOS X. While it
+ is anticipated that a future update from Apple will fix this problem, you
+ can use gcc 3 to work around it.
+
+
+ As a final note, when coding Allegro programs don't forget that you
+ need to use the END_OF_MAIN() macro right after your main() function!
+
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/build/mingw32.html b/lib/allegro/allegro-htmldocs-4.2.1/build/mingw32.html
new file mode 100644
index 0000000..70bea15
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/build/mingw32.html
@@ -0,0 +1,528 @@
+
+
+Notes on building the MinGW/Cygwin version of Allegro.
+
+
+
+
+
+ ______ ___ ___
+ /\ _ \ /\_ \ /\_ \
+ \ \ \L\ \\//\ \ \//\ \ __ __ _ __ ___
+ \ \ __ \ \ \ \ \ \ \ /'__`\ /'_ `\/\`'__\/ __`\
+ \ \ \/\ \ \_\ \_ \_\ \_/\ __//\ \L\ \ \ \//\ \L\ \
+ \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
+ \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
+ /\____/
+ \_/__/
+
+
+ Notes on building the MinGW/Cygwin version of Allegro.
+
+ Written by Henrik Stokseth.
+
+ Robert J Ohannessian added some updates to the installation instructions
+ and an example on how to use Dev-C++ with Allegro.
+
+ Elias Pschernig and Hein Zelle revamped the cross-compilation section.
+
+ Andrei Ellman updated the Cygwin section.
+
+ Michal Molhanec simplified the Dev-C++ instructions.
+
+ See readme.txt for a more general overview.
+
+ This is a complete MinGW port of Allegro. This build doesn't rely
+ on the DLL files produced by MSVC any longer but can make them itself.
+ I'm proud to say Allegro can now make Win32 programs entirely using
+ free professional tools. On that note I'd like to thank Peter Puck for
+ making this a reality and for finishing off what I started. Enjoy!
+
+
+ The screensaver example is built, but you must copy scrsave.scr to
+ your windows/system directory (or winnt/system32 directory
+ under Windows NT/2k/XP) if you want to test it.
+
+
+ If you have both GNU bash and GNU fileutils installed on your system, then
+ set the environment variable UNIX_TOOLS (set UNIX_TOOLS=1). This is needed
+ because GNU make will automatically use sh.exe instead of command.com if
+ it finds it somewhere in the PATH. This step is not necessary when using
+ MSYS or Cygwin as the makefile automatically sets UNIX_TOOLS for you.
+
+
+ "make depend" and "fixdll.bat" require that you have GNU sed installed.
+ "fixdll.bat" requires that you have GNU sort (not DOS sort!) installed.
+ You can download some extra utilities for MinGW from:
+ 'http://sourceforge.net/projects/gnuwin32/'
+
+
+
+
+ You have four choices when it comes to installing MinGW and Allegro
+ on your computer:
+
+
The section 'Setting up MinGW to build Allegro' describes how to set
+ up the MinGW command line tools which is the preferred choice for
+ those who like to work on the command line.
+
+
The section 'Setting up Dev-C++ to build Allegro' describes how to set
+ up the Dev-C++ environment to work with Allegro. This is the preferred
+ choice for those who like to work in a graphical development environment.
+
+
The section 'Setting up Cygwin to build Allegro' describes how to set
+ up your Cygwin compiler to build Allegro. Cygwin offers a mature
+ Unix-like environment for you to work in.
+
+
The last section 'Cross compilation' describes how to set up the
+ MinGW command line tools to compile Win32 programs from your Linux
+ box.
+
+ Note: You will need a program to decompress .zip, .tar.gz and optionally
+ .tar.bz2 files. I recommend PowerArchiver (shareware) which can be
+ downloaded from: 'http://www.powerarchiver.com'.
+
+
+
+
+ 1. Make sure you have a working MinGW installation. You can download the
+ complete distribution or individual packages from 'http://www.mingw.org'
+ or 'http://sourceforge.net/projects/mingw/'. You can also use
+ the Minimal SYStem (MSYS) environment with Allegro.
+
+
+ 2. Get the minimal DirectX 7 SDK for MinGW (dx70_mgw.zip). You
+ download it from 'http://alleg.sourceforge.net/wip.html'. Note
+ that this is *not* the same package as 'dx70_min.zip'. Unzip it
+ to the compiler directory, overwriting any existing files.
+
+
+ 3. Set the environment variable MINGDIR to the compiler directory. If you
+ use Windows 9x, you can add the line
+
+ set MINGDIR=c:\MinGW
+
+ to your 'c:\autoexec.bat' file, assuming 'c:\MinGW' is the compiler
+ directory, and reboot. If you use Windows ME, you can run 'msconfig',
+ select the 'Environment' tab and then add MINGDIR. If you use
+ Windows NT/2k/XP, you can open the Control Panel, click the 'System'
+ applet, the 'Advanced' tab and finally the 'Environment' button, and
+ then add MINGDIR. If you use MSYS, add instead the line
+
+ export MINGDIR=/mingw
+
+ to your 'c:\msys\etc\profile' file.
+
+
+ Test the installation by typing the following on the command line:
+ 'gcc -v'. The answer should be similar to:
+
+ If you don't know how to open a terminal, you can click on 'Start -> Run'
+ then type "command". Under Windows 2k/XP, you should type "cmd" instead.
+
+
+
+
+ Note: we assume that the complete version of the Dev-C++ environment (i.e
+ with the bundled MinGW compiler) is used. If you use instead Dev-C++ as
+ a mere IDE on top of an already installed MinGW compiler, follow the
+ instructions given in the previous section.
+
+
+ The procedure is as follows:
+
+
+ 1. Make sure you have a working Dev-C++ installation. You can download the
+ complete version from 'http://bloodshed.net/dev/devcpp.html'.
+
+
+ 2. Get the DirectX SDK: go to Tools\Check for Updates/Packages... and
+ install the DirectX package. Close Dev-C++.
+
+
+ 3. Add 'c:\DevCpp\bin' to the beginning of your PATH environment variable
+ and set the environment variable MINGDIR to 'c:\DevCpp'. If you use
+ Windows 9x, you can add the lines
+
+ PATH=c:\DevCpp\bin;%PATH%
+ set MINGDIR=c:\DevCpp
+
+ to your 'c:\autoexec.bat' file and reboot. If you use Windows ME, you
+ can run 'msconfig', select the 'Environment' tab, then modify PATH and
+ add MINGDIR. If you use Windows NT/2k/XP, you can open the Control
+ Panel, click the 'System' applet, the 'Advanced' tab and finally the
+ 'Environment' button, then modify PATH and add MINGDIR.
+
+
+
+ Test the installation by typing the following on the command line:
+ 'gcc -v'. The answer should be similar to:
+
+ If you don't know how to open a terminal, you can click on 'Start -> Run'
+ then type "command". Under Windows 2k/XP, you should type "cmd" instead.
+
+
+
+
+ 1. Make sure you have a working Cygwin installation. You can download the
+ setup.exe program from 'http://sources.redhat.com/cygwin/'.
+ You will need the followin packages: bash, binutils, cygwin, cygutils,
+ fileutils, gcc, gdb, login, make, man, mingw-runtime, sed, sh-utils,
+ texinfo, textutils and w32api.
+
+
+ 2. Get the minimal DirectX 7 SDK for MinGW. (dx70_mgw.zip) Download it
+ from 'http://alleg.sourceforge.net/wip.html' and unzip it to a
+ temporary directory, for instance 'C:\Temp'. Then move the contents of
+ 'C:\Temp\lib' to 'C:\cygwin\lib\w32api', and the contents of
+ 'C:\Temp\include' to 'c:\cygwin\usr\include\w32api'. If you are asked
+ if you want to overwrite any existing files, choose to overwrite them.
+
+
+ 3. Put the following text in '/etc/profile' (c:\cygwin\etc\profile)
+
+ Note: if the CPATH or LIBRARY_PATH variables are already set, you will
+ have to append the new path to the existing one by using a colon (":")
+ as the separator.
+
+
+
+ Test the installation by typing the following in the Bash shell:
+ 'gcc -v'. The answer should be similar to:
+
+ Reading specs from /usr/lib/gcc-lib/i686-pc-cygwin/3.2/specs
+ gcc version 3.2 20020927 (prerelease)
+
+ Note: if you have problems installing the profiling version of the Allegro
+ library, you will probably need to copy a file called libgmon.a from the
+ MinGW distribution to your /lib/mingw directory (c:\cygwin\lib\mingw) in
+ Cygwin. This is expected to be fixed in a later release of the
+ mingw-runtime package (I'm currently using mingw-runtime-1.2-1).
+
+
+
+
using a more convenient script with instructions for downloading:
+ http://www.libsdl.org/extras/win32/cross/README.txt.
+ Follow the instructions, and make sure to edit the build-crosh.sh
+ script so it downloads the most recent version of gcc and binutils.
+
+
as a premade Debian package called 'mingw32', which you can install
+ with 'apt-get install mingw32'.
+
+ 2. Get the minimal DirectX 7 SDK for MinGW (dx70_mgw.zip).
+ Download it from 'http://alleg.sourceforge.net/wip.html' and unzip it
+ in the cross-compiler base directory. Make sure you convert all text
+ files to unix style (unzip -a) or the preprocessor will croak. The
+ DirectX package downloaded and installed by the SDL script is not up
+ to date: replace it with the package from the Allegro site.
+
+
+ 3. Edit the file 'xmake.sh' in the root of your Allegro directory,
+ replacing XC_PATH, XPREFIX and INSTALL_BASE with the right names.
+ For example, if your compiler's base dir (the one with bin, lib and
+ include sub-folders) is /usr/i586-mingw32msvc, and you have prefix-less
+ binaries in /usr/i586-mingw32msvc/bin, you would use:
+
+ Note that the build-cross.sh script from SDL installs binaries both
+ with and without prefix, but some binaries (windres specifically)
+ are installed only with prefix. If you installed the crosscompiler
+ in /opt/cross-tools using this script, you would use:
+
+ 4. Run './fix.sh mingw --dtou' (--dtou is only needed if your Allegro
+ directory has text files in DOS format, otherwise you can use --quick).
+ If you are using a CVS version of Allegro, run 'make depend' to
+ generate the build dependencies, then run 'misc/fixdll.sh' to generate
+ the allegro.def file. You are now finished with all the preparations.
+
+
+ 5. You can now run './xmake.sh' to build the Allegro library and then run
+ './xmake.sh install' as root to install it. Afterwards, you can use
+ 'xmake.sh' as you would use 'make' to compile your Allegro programs, or
+ you can use the 'cross-make.sh' and 'cross-configure.sh' scripts from
+ the SDL site. You must use 'xmake.sh' to compile Allegro itself though.
+
+
+ 6. To build the documentation, use the native build process. This
+ limitation will eventually be removed.
+
+ This assumes you have unzipped allegro to c:\allegro or, if you are using
+ MSYS, you have unzipped it to c:\msys\allegro (which is equivalent to
+ /allegro from within the MSYS environment) or, if you are using Cygwin,
+ you have unzipped it to c:\cygwin\allegro (which is equivalent to
+ /allegro from within the Cygwin environment).
+
+
+ First configure Allegro for MinGW. Unless you are using MSYS or Cygwin,
+ enter the following on the commandline (click on 'Start -> Run' then type
+ "command" or "cmd" to get a command prompt):
+
+ cd c:\allegro
+ fix.bat mingw
+
+ If you are using MSYS or Cygwin, start your environment, which you can
+ find either on your desktop and/or on your Windows start menu. The
+ following commands should then be used instead of the ones above:
+
+ cd /allegro
+ ./fix.sh mingw --dtou (--dtou can be replaced by --quick for MSYS).
+
+ Now you're ready to build the Allegro library with:
+
+ make (or mingw32-make if you are using a recent version of MinGW)
+
+ The dynamically linked version of Allegro gets built by default. If you
+ want to build the statically linked version of Allegro, use:
+
+ make STATICLINK=1
+
+ If you want to build either the debug or the profile version of the
+ library, enter one of the following commands:
+
+ make DEBUGMODE=1 (dynamically linked)
+ make DEBUGMODE=1 STATICLINK=1 (statically linked)
+ make PROFILEMODE=1 (dynamically linked)
+ make PROFILEMODE=1 STATICLINK=1 (statically linked)
+
+ A list of all the available options:
+
+
+
CROSSCOMPILE
+ Set this if you are crosscompiling; it implies UNIX_TOOLS.
+
+
+
WARNMODE
+ Set this if you want Allegro to display and stop on nearly all
+ warnings issued by the compiler. Allegro should compile fine with
+ this set.
+
+
+
TARGET_ARCH_COMPAT
+ or
+ TARGET_ARCH_EXCL
+ These affect the level of processor dependant optimisation that
+ Allegro uses. You can set either of these to the processor type you
+ want to optimize for. The difference between these two is that
+ TARGET_ARCH_COMPAT optimise for the given processor so that the code
+ will still run on older processors, while TARGET_ARCH_EXCL will
+ generate code that will run exclusively on the given processor and of
+ course newer ones. Example: set TARGET_ARCH_COMPAT=i686
+
+
+
TARGET_OPTS
+ Affects the general optimisations that Allegro uses.
+
+
+
UNIX_TOOLS
+ If your system does not have the usual DOS tools available (`md',
+ `rd', `copy', etc., and commands which understand the \ character),
+ then set this to 1 to use the Unix equivalents. This is set
+ implicitly when you set CROSSCOMPILE, and is also set automatically
+ when you are running under bash.
+
+
+ To activate any of these, type (for example) "make WARNMODE=1".
+
+
+ If your copy of Allegro does not include the linker .def file (unlikely,
+ unless you have run "make veryclean" at some point, or are using the CVS
+ version of Allegro), you can regenerate it by running "misc\fixdll.bat".
+ You will need to have GNU sed and sort installed for this operation to
+ work. The version of sed that is linked from the MinGW site does not
+ work properly; it has issues with end-of-line characters. You should get
+ sed and sort from the link at the top of this document.
+
+
+ Once the build is finished you can recover some disk space by running
+ "make compress", which uses the UPX program to compress the executable
+ files and the optimized dll. Before running "make compress", you must set
+ the environment variable UPX_BIN to point to upx.exe. You will have to
+ do run "make compress" before "make install" if you want the compressed
+ dll to be copied to the windows directory. To recover even more disk
+ space, you can run "make clean" to get rid of all the temporary files and
+ HTML format documentation.
+
+
+ And then the last thing, installing the library. Run:
+
+ make install
+
+ with the same options you passed to 'make' in order to build the library.
+
+
+ You have now installed Allegro! See the rest of the documentation and
+ examples to learn more about it.
+
+
+
+
+ All the Allegro functions, variables, and data structures are defined
+ in allegro.h. You should include this in your programs, and link with
+ either the optimised library liballeg.a, the debugging library
+ liballd.a, or the profiling library liballp.a. You should include the
+ Allegro DLLs in any software you release to the public.
+
+
+ When using a statically linked library, you must define the preprocessor
+ symbol ALLEGRO_STATICLINK before including any of the Allegro headers and
+ link your program against Allegro and the main Win32/DirectX libraries
+ in that order (see the variable LIBRARIES in makefile.mgw). The names of
+ the statically linked Allegro libraries are post-fixed with '_s' so that
+ you will link with either liballeg_s.a, liballd_s.a or liballp_s.a.
+
+
+ Don't forget that you need to use the END_OF_MAIN() macro right after
+ your main() function.
+
+
+
+
+ A simple example on how to create a little program with Dev-C++:
+
+
+ Launch Dev-C++ and create a new project (File/New Project). Select
+ "Windows Application", then click on the "Ok" button. Name your
+ project and give associate it to a new file. You should now see a
+ sample code in a window. Close that window since you won't be
+ needing it (Allegro is much simpler to use than this). Create a
+ new file (File/New Source File), then write a small Allegro
+ program. You can inspire yourself by the Allegro examples if you
+ wish. Here's a small program you can type to see if everything
+ worked until now:
+
+ You now need to tell Dev-C++ that you'd like to make a program that
+ uses Allegro. For that, go in the Project Options screen
+ (Project/Project Options menu), then enter -lalleg (or -lalld for
+ the debug mode) in the box under 'Further object file or linker
+ options' or select 'Parameters tab' and enter -lalleg (or -lalld for
+ the debug mode) in the box under 'Linker'.
+
+
+ Compile your project! Simply click on the green check mark on
+ your Dev-C++ toolbar. Correct any syntax errors in your code,
+ then click on "Execute" to run the program. If all worked
+ you will see a message box pop up with "Hello World" inside of it.
+
+
+ The screensaver example is built, but you must copy scrsave.scr to
+ your windows/system directory (or winnt/system32 directory
+ under Windows NT/2k/XP) if you want to test it.
+
+
+
+
Recent set of DirectX and other Windows SDK headers.
+
A GNU environment to run GNU tools with, such as DJGPP, MinGW or Cygwin.
+ Depending on which one you choose, you will need the following packages:
+
+
DJGPP: compiler (djdev*.zip, gcc*b.zip, bnu*b.zip).
+ GNU make (mak*b.zip).
+ Optional: GNU sed (sed*b.zip). Used by "make depend" and
+ "fixdll.bat".
+ Optional: GNU sort (txt*b.zip). Used by "fixdll.bat".
+
+
MinGW: compiler (mingw-runtime, gcc, binutils).
+ GNU make.
+ Optional: GNU sed. Used by "make depend" and "fixdll.bat".
+ Optional: GNU sort (textutils). Used by "fixdll.bat".
+ Optional: w32api. See next section about details.
+
+
Cygwin: compiler (cygwin, gcc, binutils).
+ GNU make.
+ Optional: GNU sed. Used by "make depend" and "fixdll.sh"
+ Optional: GNU sort (textutils). Used by "fixdll.sh".
+
+ Allegro should work ok with MSVC versions 4, 5, 6, 7.0 (.NET),
+ 7.1 (.NET 2003) and 8.0 (.NET 2005). However note that the lowest tested
+ version is 6.
+
+
+ The DirectX SDK can be obtained directly from Microsoft. An old version
+ of the headers is included with MSVC 6, but Allegro requires more recent
+ files. You should either copy the current headers into your MSVC include
+ and lib directories, or alter your INCLUDE and LIB environment variables
+ to put the DirectX SDK files in front of the standard MSVC locations.
+
+
+ If you choose to use DJGPP as your GNU environment, the DJGPP compiler and
+ associated tools can be downloaded from your nearest SimTel mirror site,
+ in the /pub/simtelnet/gnu/djgpp/ directory, or you can use the zip picker
+ on http://www.delorie.com/djgpp/. See the djgpp readme.1st file for
+ informations about how to install DJGPP.
+
+
+ If you choose MinGW, download the MinGW compiler and associated tools from
+ 'http://www.mingw.org' or 'http://sourceforge.net/projects/mingw/'. You
+ can download the complete distribution instead of the individual packages
+ if you don't want to install each package manually.
+
+
+ If you choose Cygwin, get setup.exe from 'http://sources.redhat.com/cygwin/'.
+ Start the Cygwin setup program and download the required packages. Then
+ install the packages (run setup.exe once more). When setup asks you which
+ line endings you want, select unix-style instead of DOS.
+
+
+ Remember that the chosen set of tools have to be on your PATH during the
+ building of Allegro.
+
+
+
+
+ This is a source-only distribution, so you will have to compile Allegro
+ before you can use it. To do this you should:
+
+
+ Set up your environment so that MSVC can be used from the commandline.
+ You probably have a vcvars32.bat file that will do this for you (usually
+ located in the VC98\BIN folder where you have MSVC installed, for example
+ C:\Program Files\Microsoft Visual Studio\). Under either Windows NT or
+ Windows 2000, you will have to run this file every time you open a DOS box
+ or configure the environment variables in Control Panel/System/Environment.
+
+
+ The make process needs all the path variables to be in DOS 8.3 format, and
+ since MSVC is usually installed in something like
+ "C:\Program Files\Microsoft\Microsoft Visual Studio .NET 2003",
+ this will cause a problem. Run "echo %MSVCDir%" (%VCINSTALLDIR%
+ under MSVC 8) from the command line to see if you have this problem.
+ If you are using MSVC 6 or lower the output should already be in DOS 8.3
+ format so you should not have any troubles. With higher versions of MSVC
+ it will probably show the long path with spaces. There are two solutions
+ for this.
+
+
+ If you have chosen MinGW and have installed it with the w32api package
+ you can solve this problem simply by passing the --msvcpaths
+ parameter to fix.bat (see below).
+
+
+ Otherwise if you are using vcvars32.bat, you will have to
+ edit it so that it sets the 8.3 paths, not the long versions.
+ To get 8.3 path names, you can use the command prompt (cmd.exe).
+ Type in "dir /x" to get a listing of the 8.3 file and directory
+ names alongside of their full names. You can also use the DOS prompt
+ (command.exe) and "dir", but this will only show
+ you the 8.3 names.
+
+
+ If you are using Cygwin as the GNU environment, start the Cygwin bash shell
+ from the command prompt (if you used the command prompt to run vcvars32.bat
+ then you must start Cygwin in the same command-prompt window you used to
+ run vcvars32.bat unless you configured the environment variables in Control
+ Panel/System/Environment). This is usually done via "C:\cygwin\cygwin.bat".
+
+
+ Go to the directory where you have installed Allegro by using 'cd'.
+
+
+ If you are using Cygwin, type "./fix.sh msvc --utod". Otherwise (i.e if
+ you are using DJGPP or MinGW), type "fix.bat msvc". If you are
+ using MinGW and want the fix.bat to solve problems with long paths,
+ type "fix.bat msvc --msvcpaths".
+
+
+ If you are using MSVC 7 you can specify "msvc7" instead of "msvc" to enable
+ better optimizations. Likewise, you can specify "icl" to use the Intel
+ commandline compiler. If you are using MSVC 8 you should specify "msvc8"
+ otherwise you will get a lot of deprecation warnings. For MSVC 6 and older
+ you can use also "msvc6".
+
+
+ If you are compiling from CVS, before continuing you must run both
+ "make depend" and "misc/fixdll.sh" as explained below, or the build will
+ fail asking for some .inc file.
+
+
+ Type "make". Then go do something interesting while everything compiles.
+ When it finishes compiling, type "make install" to set the library up
+ ready for use.
+
+
+ If you also want to install a debugging version of the library (highly
+ recommended), now type "make install DEBUGMODE=1". Case is important, so
+ it must be DEBUGMODE, not debugmode!
+
+
+ If you also want to install a profiling version of the library, now type
+ "make install PROFILEMODE=1".
+
+
+ If you want statically linked libraries as well as the default DLLs, pass
+ additionally "STATICLINK=1" to the make commands above.
+
+
+ If your copy of Allegro doesn't include the makefile.dep dependency files
+ (unlikely, unless you have run "make veryclean" at some point or are
+ building the CVS version), you can regenerate them by running
+ "make depend".
+
+
+ If your copy of Allegro doesn't include the linker .def file (unlikely,
+ unless you have run "make veryclean" at some point or are building the CVS
+ version), you can regenerate it by running "misc\fixdll.bat". Cygwin users
+ can run "misc/fixdll.sh" instead.
+
+
+ Once the build is finished you can recover some disk space by running
+ "make compress", which uses the UPX program to compress the executable
+ files and the optimized dll. Before running "make compress", you must set
+ the environment variable UPX_BIN to point to upx.exe. You will have to
+ do run "make compress" before "make install" if you want the compressed
+ dll to be copied to the windows directory. To recover even more disk
+ space, you can run "make clean" to get rid of all the temporary files and
+ HTML format documentation.
+
+
+
+
+ All the Allegro functions, variables, and data structures are defined in
+ allegro.h. You should include this in your programs, and link with one of
+ the libraries:
+
+ When using a statically linked library, you must define the preprocessor
+ symbol ALLEGRO_STATICLINK before including any of the Allegro headers and
+ link your program against Allegro and the main Win32/DirectX libraries
+ in that order (see the variable LIBRARIES in makefile.vc). You have also
+ to make sure that your program is linked against the right C run-time
+ library, ie. the multi-threaded DLL version of MSVCRT (or the debug
+ version if you are using the debug library). You can change this option
+ at Project - Settings - C/C++ - Category: Code Generation - Use run-time
+ library.
+
+
+ Don't forget that you need to use the END_OF_MAIN() macro right after
+ your main() function!
+
+
+ If you use one of the DLL versions, you will obviously need to distribute
+ the appropriate DLL along with your program: these can be found in the
+ allegro/lib/msvc/ directory.
+
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/build/qnx.html b/lib/allegro/allegro-htmldocs-4.2.1/build/qnx.html
new file mode 100644
index 0000000..c915b44
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/build/qnx.html
@@ -0,0 +1,118 @@
+
+
+ Status: it works. Only annoying bug left seems to be the display switching
+ in fullscreen mode; just don't try to change workspace while in fullscreen
+ or your program will crash... Also, video bitmaps and hardware acceleration
+ are still not yet implemented.
+
+
+
+
+ The library works with QNX 6.0 RTP. You need the development tools
+ installed on your system; if you don't have them, you can get them from the
+ QNX online repository using the Package Manager.
+
+
+
+
+ As Allegro is a multiplatform library, you first need to set it up for use
+ on QNX RTP, by running:
+
+ chmod +x fix.sh
+ ./fix.sh qnx
+
+ Now you may want to generate the dependencies; this step is optional if
+ you are using an official release, but it is required if you got a CVS
+ snapshot of the library.
+
+ make depend
+
+ Then you need to build Allegro:
+
+ make
+
+ And finally install it (you need to be root for this):
+
+ su -c "make install"
+
+ Installing the library will copy the header files to /usr/include, the
+ library file to /usr/lib and the allegro-config script into /usr/bin.
+
+
+
+
+ Linking with Allegro requires you to link also other libraries to your
+ executables. To avoid you having to work out the right linker commands for
+ yourself, the installation creates a script, allegro-config, that will
+ print out a suitable commandline. You can use this inside a backtick
+ command substitution, for example:
+
+ Unix newbies, take note that these are ` backticks, not normal ' quotes!
+
+
+ There are also switches for printing out the Allegro version number and
+ overriding the install paths. Run allegro-config without any arguments
+ for a full list of options.
+
+
+ Don't forget that you need to use the END_OF_MAIN() macro right after
+ your main() function!
+
+
+
+
+ Allegro for QNX requires you to be running the Photon MicroGUI environment;
+ if Photon cannot be found, the library will fail to initialize. If this
+ happens, you're probably in a text console; just run "ph" to start Photon.
+
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/build/tmpfile.txt b/lib/allegro/allegro-htmldocs-4.2.1/build/tmpfile.txt
new file mode 100644
index 0000000..18f7a67
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/build/tmpfile.txt
@@ -0,0 +1 @@
+This file is needed because some unzip programs skip empty directories.
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/build/unix.html b/lib/allegro/allegro-htmldocs-4.2.1/build/unix.html
new file mode 100644
index 0000000..1c01e6a
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/build/unix.html
@@ -0,0 +1,376 @@
+
+
+ On Linux you have two different system drivers -- one for running using
+ X, and one for running without X. This file describes the X version,
+ which should in theory be totally portable to any Unix variant. For
+ information about the Linux-specific console routines, see
+ docs/build/linux.txt.
+
+
+
+
+ Since you are using a Real Operating System, the chances are that you
+ already have all the necessary development tools, at least for compiling
+ and installing the library. However, you may also need GNU autoconf if you
+ make any changes that require you to regenerate the configure script.
+
+
+
+
+ If you downloaded Allegro as a Unix format .tar archive, it will already
+ be set up ready to go. If you downloaded a DOS or Windows format .zip
+ version, though, you will need to convert it into Unix format before you
+ can begin, by running:
+
+ chmod +x fix.sh
+ ./fix.sh unix
+
+ From here on everything is a pretty standard Unix-style install process.
+ First you configure it:
+
+ ./configure
+
+ It should automatically build dependencies. Then you build it:
+
+ make
+
+ And finally you install it (as root -- see below for information on what
+ to do if you can't be root):
+
+ su -c "make install"
+
+ You may also wish to install the man pages:
+
+ su -c "make install-man"
+
+ And perhaps the info docs as well:
+
+ su -c "make install-info"
+
+ The configure script has many options for changing the install paths,
+ deciding which parts of the library to include or leave out, and
+ specifying whether to build release libs, debug libs, etc. Run
+ ./configure --help for a list of switches. Especially useful options are:
+
+ --enable-static - builds a statically linked library
+ --disable-shared - disables the default shared libraries
+ --enable-dbglib - builds a debug version of the library
+ --enable-dbgprog - links test programs with the debug library
+
+ These switches work in combination, for example if you pass
+ --enable-static but not --disable-shared, you will get both shared and
+ statically linked versions of Allegro.
+
+
+ By default, Allegro will probably install into the /usr/local filesystem.
+ If this hasn't already been set up on your machine, you may have trouble
+ with programs being unable to find the Allegro shared library. On some
+ Unices (for example Linux), you can fix this by adding "/usr/local/lib" to
+ your /etc/ld.so.conf file and then running `ldconfig' as root. On others
+ (for example Solaris), you can hardcode the location of the library into
+ the executables by passing "-R/usr/local/lib" to the compiler or linker.
+ Alternatively, you can add the path to your LD_LIBRARY_PATH environment
+ variable.
+
+
+ If you are compiling a CVS version of Allegro, you need to generate the
+ configure header and script prior to doing anything else. Make sure that
+ GNU autoconf 2.53 or newer is installed on your system and type:
+
+ autoheader
+ autoconf
+
+ It is possible to add compilation and link flags to the make command line.
+ This is done by passing CFLAGS and/or LDFLAGS to make, with the flags
+ you want. This is meant as a generic customization ability and you should
+ really use configure to set the flags if possible. Note that any flags you
+ pass using the make command line are transient: they will only apply to
+ whatever compilation and link happen to be spawned by this particular
+ invokation of make.
+ When you pass CFLAGS and/or LDFLAGS to the make command line Allegro's
+ build system will use these as a starting point and will add its own
+ flags to those. This means that you should be aware that flags you pass
+ this way may be overridden. For this reason, it is best to only use this
+ to specify flags that do not interfere with the code generation. Useful
+ flags to pass are -save-temps, or -pipe.
+
+
+
+
+ Installing Allegro will copy the library and header files plus other
+ support files. These are:
+
+ allegro-config: Script that outputs the correct compiler and linker flags
+ for your system in order to compile Allegro. This is copied into a
+ `.../bin' path.
+
+ allegro.m4: Autoconf support file to include in your `./configure'
+ scripts. Copied into a `.../share/aclocal' path.
+
+ On the other hand, there are files which you, as system administrator, are
+ required to installed manually. These are:
+
+ language.dat: Contains translations for text strings used by Allegro. If
+ this file is not available, Allegro runtime messages will only speak
+ English. Recommended location is `/usr[/local]/share/allegro'.
+
+ allegro.info: Allegro documentation in Info format, viewable with GNU's
+ info viewer. This is copied into the correct `.../info' path of your
+ system if you run `make install-info'.
+
+ allegro.cfg: Contains configuration settings for your system when the
+ hardware autodetection fails. You can either copy this file and edit
+ the contents manually or you can use Allegro's setup configuration
+ program (in the `setup' directory) to create this file. Recommended
+ location is `[/usr/local]/etc/allegro.cfg'.
+
+ You can find more information about some of these files and other
+ suggestions in the chapter "Unix specifics" of the main Allegro manual.
+
+
+
+
+ The options for linking with Allegro are quite complicated, since
+ for static versions of the library, depending on how it was configured,
+ it may need to pull in other libraries (X, SVGAlib), as well as just
+ Allegro itself, and for all versions the library is split into two chunks
+ -- one of which is always static, and the other of which is sometimes
+ shared. To avoid you having to work out the right linker commands for
+ yourself, the installation creates a script, allegro-config, that will
+ print out a suitable commandline. You can use this inside a backtick
+ command substitution, for example:
+
+ Unix newbies, take note that these are ` backticks, not normal ' quotes!
+
+
+ There are also switches for printing out the Allegro version number,
+ overriding the install paths, and selecting between shared and static
+ libraries, in case you installed both. Run allegro-config without any
+ arguments for a full list of options.
+
+
+ Don't forget that you need to use the END_OF_MAIN() macro right after
+ your main() function!
+
+
+
+
+ You can set the X11 icon for your application to use. To do this, you need
+ to include the icon in .xpm format and then point the symbol allegro_icon
+ to the .xpm data before calling set_gfx_mode().
+ Alternatively, you can use the xfixicon.sh shellscript to produce a C file
+ that will do this for you automatically when you link it with your project.
+ No other steps are required. The xfixicon.sh utility will also accept
+ bitmaps that are not in .xpm format, interpreting magic pink as transparent.
+ You will need to have the ImageMagik tools installed for this to work.
+
+
+
+
+ Allegro can interface with a lot of other libraries -- in particular,
+ various X libraries and SVGAlib. If you link statically to Allegro,
+ your program will depend upon all these other libraries so you may want
+ to link statically to them too. If you link dynamically to Allegro, your
+ binary will only depend upon the Allegro version (and things like libc);
+ in this case your binary is more easily portable, but it does depend
+ upon the way Allegro was configured.
+
+
+ The easiest way to make your program portable is to distribute it in
+ source form. That way the users can configure Allegro for themselves,
+ and will always end up using exactly the right set of libraries for
+ their particular system.
+
+
+ Having said that, if you enable dynamic module support (default), then
+ you should have few (if any) problems.
+
+
+ Security note: Make sure that untrusted users cannot write to either of
+ the `/usr/local/lib/allegro/' or `/usr/lib/allegro/' directories.
+ Allegro looks for dynamically loaded modules in those directories, and
+ loads all of them listed in `modules.lst' at startup.
+
+
+ See also the ABI compatibility document for more information (abi.txt).
+
+
+
+
+ Allegro can be installed on a system where you don't have root
+ privileges. Using the standard configure script option `--prefix' you
+ can change the target directories for installation -- for example,
+ you can write:
+
+ ./configure --prefix=$HOME
+
+ Be a bit careful, --prefix=~ works in bash but not tcsh -- it's safer
+ to use $HOME if you're not sure.
+
+
+ Then binaries will be installed to the `bin' subdirectory of your home
+ directory, libraries to `lib', etc. Now you need to set up your system
+ so that it knows where to find a few things, if this has not been done
+ already. You might want to add these commands to your .bash_profile
+ or similar startup script. If you use a csh-style shell, you want to
+ use `setenv', not `export'.
+
+
+ Your PATH must include the `bin' directory:
+
+ export PATH=$PATH:$HOME/bin
+
+ If you are using Allegro as a shared library, you need to tell the dynamic
+ loader where to find the Allegro libraries:
+
+ But, it's better to set the environment variables too. Most people
+ don't tend to bother with `allegro-config' when compiling.
+
+
+ Alternatively, you can get the required environment changes from
+ allegro-config, by typing at a shell prompt:
+
+ allegro-config --env
+
+ You can catenate the output to your .bash_profile, which is pretty
+ much like adding all of the above commands. Note that `allegro-config'
+ itself is in the `bin' directory of the installation, so either make
+ sure that directory is in your path before running `allegro-config' or
+ specify the path exactly, for example:
+
+ On initialisation, Allegro will try to connect to an X server. If it
+ can't find one, it will give up and try to use some different system
+ driver instead (such as the Linux console). This means that to run
+ it in X mode, you must either launch your programs from inside an X
+ session, or have set the DISPLAY environment variable to indicate
+ what server you would like to use.
+
+
+
Graphics:
+ There are two different X graphics drivers: GFX_XWINDOWS uses only
+ standard X calls, while GFX_XDGA2 uses the XFree86 DGA 2.0 extension
+ (shipped with XFree86 4.0.x) which allows it to write directly to the
+ screen surface, and use hardware acceleration if available. It is
+ normally much faster than the standard X mode, but requires root
+ permissions and will not work remotely.
+
+
+ If your program requests a different color depth to the current X
+ display, Allegro will emulate the depth you asked for, so that your
+ program will still work, albeit more slowly than if the color depths
+ were identical. To find out whether this emulation is taking place,
+ look at the gfx_driver->desc field (which is displayed in the middle of
+ the screen by the tests/test program). If this says "matching", the
+ color formats are identical, so no conversions are required. If it says
+ "fast", some simple conversions are taking place, but nothing too
+ painful. If it says "slow", you are in trouble :-) This is not valid
+ for the DGA 2.0 driver, as it'll always change the video mode to the
+ specified resolution and color depth.
+ Status: complete and fully functional, but not so widely used and tested
+ as the djgpp code. This version is heavily based on the djgpp version,
+ basically just emulating whatever parts of the djgpp libc aren't provided
+ by Watcom. See docs/build/djgpp.txt for information about the available
+ hardware drivers: the djgpp and Watcom versions are 100% identical in this
+ respect.
+
+
+ This library works with version 10.6 and the various 11.0 versions of the
+ Watcom C compiler, as well as with Open Watcom 1.0 or later.
+
+
+
+
Watcom C version 10.6 or 11.0x, or Open Watcom 1.0 or later.
+
djgpp compiler (djdev*.zip, gcc*b.zip, and bnu*b.zip).
+
GNU make (mak*b.zip).
+
GNU sed (sed*b.zip):
+ Required for 10.6: Used to build asm sources.
+ Optional for other versions: Used by "make depend".
+
+ Except for the Watcom compiler itself, all of the above packages can be
+ downloaded from your nearest SimTel mirror site, in the
+ /pub/simtelnet/gnu/djgpp/ directory, or you can use the zip picker on
+ http://www.delorie.com/djgpp/. See the djgpp readme.1st file for
+ information about how to install djgpp.
+
+
+
+
+ This is a source-only distribution, so you will have to compile Allegro
+ before you can use it. To do this you should:
+
+
+ Type "cd allegro", followed by "fix.bat watcom", followed by "make". Then
+ go do something interesting while everything compiles. When it finishes
+ compiling, type "make install" to set the library up ready for use.
+
+
+ The makefile will try to guess whether you are using Watcom 10.6 or 11.0
+ by checking for the presence of wdisasm.exe. If it gets this wrong, you
+ may need to override it by passing WATCOM_VERSION=10.6 or
+ WATCOM_VERSION=11 as arguments to make, or setting the WATCOM_VERSION
+ environment variable.
+
+
+ If you also want to install a debugging version of the library (highly
+ recommended), now type "make install DEBUGMODE=1". Case is important, so
+ it must be DEBUGMODE, not debugmode!
+
+
+ If you also want to install a profiling version of the library, now type
+ "make install PROFILEMODE=1".
+
+
+ If your copy of Allegro doesn't include the makefile.dep dependency files
+ (unlikely, unless you have run "make veryclean" at some point), you can
+ regenerate them by running "make depend".
+
+
+
+
+ All the Allegro functions, variables, and data structures are defined in
+ allegro.h. You should include this in your programs, and link with either
+ the optimised library alleg.lib, the debugging library alld.lib, or the
+ profiling library allp.lib. Programs that use Allegro must be compiled to
+ use the stack based calling convention (wcl386 option '-5s'), and with
+ stack overflow checks disabled (wcl386 option '-s'). You will also have
+ to increase the stack size from the miserly Watcom default, using a
+ wcl386 option like '-k128k', or a linker command like 'option stack=128k'.
+
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/changes.html b/lib/allegro/allegro-htmldocs-4.2.1/changes.html
new file mode 100644
index 0000000..05cb10b
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/changes.html
@@ -0,0 +1,5411 @@
+
+
+ Peter Wang made the Unix ports query the memory page size with sysconf()
+ when necessary, instead of using the PAGE_SIZE constant, which seems to be
+ Linux-specific.
+
+ Matthew Leverton gave the STATICRUNTIME builds of MSVC new names by
+ appending _crt (c run time) to the libraries. He also fixed the problem of
+ incorrectly setting the EMBED_MANIFEST variable when using the
+ STATICRUNTIME.
+
+ Andrei Ellman fixed an inverted test in pack_fopen_chunk on Windows.
+
+ Peter Hull made 32-bit icon generation by fixbundle endian-independent
+ (colours were incorrect on Intel Macs).
+
+ Peter Wang fixed a long standing bug where some compressed packfiles would not
+ be read back properly (premature EOF). Reported by jman2050.
+
+ Andrei Ellman spotted a free() of an internal buffer returned by tmpnam().
+
+ Peter Hull fixed a problem with mouse-related deadlock on MacOS X as
+ reported by Mike Farrell.
+
+ Peter Hull implemented simulation of video bitmaps on MacOS X, so that
+ page flipping will work.
+
+ Peter Hull fixed an endian problem in the digital sound driver on MacOS X.
+
+ Elias Pschernig and Chris Robinson fixed problems with UTF-8 filenames
+ under Unix, as reported by Grzegorz. Non-ASCII non-UTF-8 filenames remain
+ broken.
+
+ Chris Robinson fixed some problems with non-ASCII filenames under Windows.
+
+ Elias Pschernig made the X11 driver call XInitThreads, to make Mesa-OpenGL
+ work together with Allegro. It can be disabled at runtime through a config
+ variable.
+
+ Andrei Ellman fixed a bug in datedit.c that could crash the grabber.
+
+ Elias Pschernig added file_size_ex(), which returns a 64 bit integer
+ to handle large files.
+
+ Ron Novy made improvements to the test program.
+
+ Peter Hull fixed problems with set_mouse_sprite() on Intel Macs.
+
+ Peter Hull added universal binary support to the MacOS X port.
+
+ Peter Wang and Evert Glebbeek independently fixed a problem with dependency
+ generation for MacOS X on non-Mac systems.
+
+ Many smaller fixes and updates by Peter Hull, Elias Pschernig, Peter Wang
+ and Milan Mimica.
+
+ Michal Molhanec made msvchelp.exe work on Cygwin, where there was a
+ problem with the case-insensitivity of environment variables. Reported by
+ Milan Mimica.
+
+ Peter Hull fixed a bug where Allegro detected keypresses on
+ KEY_MINUS_PAD as KEY_PLUS_PAD.
+
+ Peter Hull made OSX work correctly with Logitech sticks, as discussed
+ with Ultio.
+
+ Milan Mimica fixed some spin loops in the test program.
+
+ Chris Robinson added UTF8/Unicode support for filenames in Windows.
+
+ Milan Mimica made the Linux console driver more robust:
+ set_gfx_mode used to get stuck in a infinite loop when there wasn't a
+ console available.
+
+ Evert Glebbeek made the C blitter use memmove for normal blits, with a bugfix
+ by Milan Mimica. This can be disabled by removing a #define USE_MEMMOVE at
+ the top of cblit.h so that it can easliy be tested against the older versions
+ of the code.
+
+ Christer Sandberg worked around a problem where one-line high bitmaps would
+ crash with Electric Fence.
+
+ Chris Robinson fixed a crash that occurred if the sound mixer quality
+ level was set to 0 after the mixer was already initialised.
+
+ Evert Glebbeek fixed the window title under X11, which was broken by a
+ previous change.
+
+ Peter Hull updated the endian detection under OSX as recommended by Apple.
+
+ Miguel A. Gavidia and Jay Bernardo made qtmidi.m work on both PPC and Intel.
+
+ Milan Mimica fixed a crash when vsync() on certain drivers.
+
+ Elias Pschernig replaced the ALLEGRO_USE_C define with ALLEGRO_NO_ASM.
+
+ Peter Wang restored the JACK driver to compiling state.
+
+ Milan Mimica made the new transparent fonts be recognized as color fonts
+ with is_color_font.
+
+ Elias Pschernig made the modules path WIP version specific, for enhanced
+ binary compatibility.
+
+ Stijn Wolters clarified the documentation of init_dialog.
+
+ Hans de Goede fixed a problem with dynamically generated stretcher code not
+ being properly marked as executable on Linux (esp. SELinux).
+
+ Hans de Goede fixed a busy wait in the X11 vsync simulation.
+
+ Elias Pschernig makde it so modules under Unix are now searched in libdir
+ as passed by the build machinery. Closes bug #1401840 from SF, reported by
+ Paul Eipper.
+
+ Milan Mimica added a get_volume and a get_hardware_volume function, to
+ work as pendants to set_volume and set_hardware_volume.
+
+ Milan Mimica corrected a case where a wrong structure on the stack was
+ being cleared in the DirectSound input driver.
+
+ Hans de Goede added a fullscreen driver for X11 which does not need
+ XVidMode extension, and instead simply centers the window on the desktop
+ and draws a black border around.
+
+ Hans de Goede fixed a problem where switching to fullscreen mode under X11.
+
+ Serge Semashko added Enter as a fire key in the demo game.
+
+ Serge Semashko added fixed problems with Allegro working on Nokia 770.
+
+ Peter Wang fixed some problems with binary compatibility checking in the
+ 4.2 branch.
+
+ Catatonic Porpoise added OpenBSD detection (in addition to FreeBSD and
+ NetBSD) and fixed an issue with executable rights not set on the memory
+ for the i386 stretcher on UNIX systems.
+
+ Hans de Goede fixed a bug preventing the ALSA driver to work on big endian
+ systems.
+
+ Elias Pschernig and Chris Robinson fixed binary compatibility checking in
+ allegro_init and install_allegro.
+
+ Catatonic Porpoise fixed the example in the documentation of
+ stretch_sprite.
+
+ Hans de Goede made DIGMID work with absolute paths in the patches.cfg file.
+
+ Peter Hull added code to make Allegro work better with user-supplied Nibs
+ under OSX, as discussed with Thomas Harte.
+
+ Matthew Leverton added embedding of manifests to the MSVC 8 build process.
+
+ Neil Walker and Thomas Harte implemented a hardware accelerated
+ stretch_blit() for the Windows DX port.
+
+ Evert Glebbeek corrected a bug when destroying sub-bitmaps under Windows.
+
+ Evert Glebbeek fixed a bug in pack_fopen_chunk() where a temporary file
+ would be created in a non-writable location.
+
+ Peter Wang changed a "/lib" option to MSVC's link utility to "-lib" as
+ reported to be problematic by Karthik Kumar.
+
+ Peter Wang fixed a crash in dat and grabber due to the return value of
+ pack_fopen_chunk() not being checked.
+
+ Elias Pschernig added support for anti-aliased bitmap fonts.
+
+ Dennis Busch fixed the short description of add_clip_rect.
+
+ Thomas Harte and Neil Walker fixed a problem with draw_sprite() and
+ sub-bitmaps.
+
+ Peter Wang fixed scancode_to_name(KEY_NUMLOCK) returning "PAUSE" in Windows.
+
+ Peter Wang fixed page flipping and triple buffering in the demo game.
+
+ Elias Pschernig added list_config_sections and list_config_entries
+ functions.
+
+ Hrvoje Ban added create_datafile_index and load_datafile_object_indexed
+ functions.
+
+ Peter Hull allowed use of "mingw" instead of "mingw32" in fix.bat and
+ fix.sh.
+
+ Peter Wang fixed a bug with SWITCH_BACKAMNESIA mode with the fbcon graphics
+ driver.
+
+ Peter Wang made the svgalib driver save and restore the palette on VT
+ switches.
+
+ Peter Wang fixed a problem with the fbcon driver and VT switching.
+
+ Milan Mimica delayed Linux console initialisation until it is required.
+ This way the user can write command-line programs using timers without
+ needing a real console.
+
+ Chris Jones fixed behavior of numeric keys when NumLock is on.
+
+ Vincent Penecherc'h worked around a problem with 24-bit bitmaps in
+ the assembler code.
+
+ Tobias Dammers fixed a problem with the DirectSound input driver.
+
+ Matthew Leverton fixed Ctrl-Alt-Del mistakenly being captured by Allegro
+ under Windows
+
+ Vincent Penecherc'h improved the implementation of set_ramp_cmap in the
+ fbcon driver.
+
+ Vincent Penecherc'h implemented get_refresh_rate for the fbcon driver.
+
+ Vincent Penecherc'h fixed problems with the fbcon driver not restoring the
+ original video mode when the driver exits.
+
+ Victor Williams Stafusa da Silva made OS type detection handle Windows 2003
+ and Windows Vista.
+
+ Chris Jones and Vincent Penecherc'h fixed load_wav to handle degenerate
+ stereo wave files with an odd length.
+
+ Annie Testes fixed all sorts of problems with the linux evdev mouse driver
+ when using a tablet as the mouse.
+
+ Annie Testes made the linux evdev mouse driver use the correct device files.
+
+ Vincent Penecherc'h made the linux fbcon driver set a ramp colourmap for
+ directcolor modes, otherwise colours in those modes were all wrong.
+
+ Vincent Penecherc'h fixed a problem with the linux fbcon driver, where it
+ would keep using the old pitch after changing resolutions.
+
+ Serge Semashko fixed a typo causing crashs in
+ _linear_draw_trans_rgba_rle_sprite24.
+
+ Annie Testes fixed cursor speed and incorrect mickey computation bugs in
+ the Linux evdev mouse driver.
+
+ Vincent Penecherc'h made the Linux PS/2 mouse driver try /dev/input/mice
+ by default, in addition to /dev/mouse.
+
+ Warnings, code formatting and minor changes to code and build system
+ by Milan Mimica, Evert Glebbeek, Elias Pschernig, Peter Wang, Peter
+ Hull, Thomas Harte, Vincent Penecherc'h and Chris Robinson.
+
+ Documentation updates by Tore Halse, Elias Pschernig, Milan Mimica,
+ Peter Wang, Physics Dave, Ryan Patterson, Grzegorz Adam Hankiewicz,
+ Andrei Ellman and Evert Glebbeek.
+
+ Peter Wang made fixmul() detect overflows as it used to do in the 4.0.x
+ branch.
+
+ Peter Hull fixed a bug in the fixbundle utility.
+
+ Dennis Busch found a bug where d_clear_proc would not work properly if the
+ GUI target bitmap is different from screen.
+
+ Grzegorz Adam Hankiewicz made Allegro log all TRACE output with a prefix
+ in the format "al-system level: ". This makes it easier to grep debug logs.
+
+ Grzegorz Adam Hankiewicz made dialogs with MSG_CHAR/MSG_UCHAR handlers
+ honor a D_CLOSE return flag without a D_USED_CHAR.
+
+ Peter Hull fixed problems with the mouse position as reported by Allegro and
+ the mouse position as known to OS X.
+
+ Peter Hull made Command-Q not close the application if no exit-button
+ callback is registered.
+
+ Peter Hull fixed problems with joysticks under MacOS X as reported by
+ Thomas Harte.
+
+ Peter Hull fixed a bug preventing more than one Allegro application from
+ being run at a time on Mac OS X. Reported by Thomas Harte.
+
+ Peter Hull did a lot of other things for the MacOS X port too.
+
+ Jiri Gabriel fixed loading of multiple ranges in a single bitmap with txt
+ fonts.
+
+ Milan Mimica and Jiri Gabriel fixed several bugs in extract_font_range.
+
+ Dennis Busch fixed a Unicode bug in the mode selector.
+
+ Grady Martin made the grabber consider deleting object properties as a
+ change to the datafile.
+
+ Milan Mimica fixed numerous bugs in extract_font_range().
+
+ Peter Hull moved the 'magic chdir' in the MacOS X port to earlier in the
+ startup process, so that the config file will be looked for in the
+ resource directory if is present.
+
+ Chris Robinson made create_bitmap(0,0) not return a bitmap that would
+ later crash destroy_bitmap(). Zero-sized bitmaps are still not allowed so
+ the assertions for debug mode have not changed.
+
+ Elias Pschernig patched the Windows keyboard driver to get key_shifts
+ working again with KB_SHIFT_FLAG, KB_CTRL_FLAG, KB_ALT_FLAG on Win98.
+
+ Peter Wang changed hline and vline into aliases for internal symbols to
+ avoid a conflict with the curses API. This change should be transparent
+ for users.
+
+ Matthew Leverton and Michal Molhanec updated the build system for MSVC 8.
+
+ Grzegorz Adam Hankiewicz prevented make_relative_filename() from crashing
+ with malformed parameters.
+
+ Hrvoje Ban made ASSERT() actually abort in Windows.
+
+ Chris Robinson made GUI menus work with gui_screen.
+
+ Evert Glebbeek fixed reading of 32 bit Windows .bmp files, which was not
+ supported. These files seem to be not very standard though, so it's
+ unclear if it will always do the right thing. Alpha channels also seem
+ not to be standard in 32 bit BMP files, so it's possible they're not read
+ in correctly.
+
+ Peter Wang and Peter Hull updated the ABI compatibility document. This
+ documents our policy for the 4.2.x series.
+
+ Extensive documentation updates from Grzegorz Adam Hankiewicz and minor
+ updates due to Michael Faerber, Robert Ohannessian and Milan Mimica.
+
+ Peter Hull fixed the MacOS X port to avoid an issue with the dead bootstrap
+ context and cleaned up the dock notification. This means command line
+ apps (with SYSTEM_NONE) run without the dock being notified.
+
+ Peter Wang Added a COLORCONV_KEEP_ALPHA flag, as suggested by Gideon Weems.
+
+ Peter Wang fixed issues with OSS in OpenBSD and made the configure script
+ print a warning if Allegro is compiled without X11 support.
+
+ Peter Hull set the compatibility version to 4.2.0 for MacOS X and added a
+ MacOS X help file.
+
+ Peter Wang made the Mode-X and VBE/AF drivers fail if Allegro is compiled
+ as a C-only library in Linux and made the Unix port install liballeg*.so
+ and the alleg-*.so modules with the execute permission enabled.
+
+ Grady Martin standardised some of the grabber dialog boxes and added a `move'
+ command to the grabber.
+
+ Evert Glebbeek fixed a bug when loading some old datafiles containing
+ monochrome fonts.
+
+ Evert Glebbeek fixed a bug that prevented system cursors from working
+ correctly in Windows.
+
+ Olivier Blin fixed compilation problems for the ModeX driver with newer
+ binutils.
+
+ Shawn Walker fixed a bug in get_executable_name under some UNIX systems.
+
+ Shawn Walker worked around a problem with some versions of GNU AS and fixed
+ some errors in the configure script when not using GCC.
+
+ Elias Pschernig made create_sample not unnecessarily clear the sample to 0.
+
+ Bobby Ferris fixed the makedoc SciTE API output.
+
+ Elias Pschernig fixed a too strict assert that prevented set_volume from
+ working in debug mode.
+
+ Paavo Ahola helped fix a problem with BCC and the C implementations of
+ fixmul.
+
+ Elias Pschernig fixed a cosmetic bug where the listbox was drawing a too big
+ selection rectangle, reported by dthompson.
+
+ Documentation and example updates by Grzegorz Adam Hankiewicz, Peter
+ Wang, Elias Pschernig Michal Molhanec and Evert Glebbeek.
+
+ Matthew Leverton changed the default behavior of the grabber: default color
+ depth is now the desktop, default mode is windowed and if fullscreen is
+ specified, then desktop resolution is used by default.
+
+ Peter Wang fixed compilation problems related to get_modex_screen() on
+ UNIX and deprecated it.
+
+ Robert Ohannessian fixed compilation problems for the assembler code with
+ newer binutils.
+
+ Peter Wang, Thomas Harte and Evert Glebbeek optimised fixmul() for different
+ platforms.
+
+ Robert Alfonso fixed a couple of warnings that with DJGPP.
+
+ Grzegorz Adam Hankiewicz made the FLIC player yield.
+
+ Miran Amon fixed an arbitrary limit in get_config_argv(). Evert Glebbeek
+ fixed a memory leak in same.
+
+ Thomas Klausner fixed a problem in allegro.m4 and automake 1.8+.
+
+ Charles Wardlaw fixed some warnings with gcc 4 on MacOS X.
+
+ Elias Pschernig removed the `256 items' limit from the dat utility.
+
+ Julien Cugniere fixed a crash in the GUI if a new dialog was opened while
+ a menu was still open.
+
+ Shawn Walker fixed crashes with the keyboard driver under Solaris.
+
+ Elias Pschernig split the demo game into multiple files and made the
+ makefile handle a multi-file demo game.
+
+ Evert Glebbeek fixed a bug where the hardware mouse wasn't displayed in
+ Windows until the mouse was moved.
+
+ J.P. Morris fixed rest_callback() under UNIX.
+
+ Shawn Walker and Evert Glebbeek fixed get_executable_name() under
+ Solaris and OpenBSD.
+
+ Peter Hull fixed compilation problems with setAppleMenu under Tiger.
+
+ Peter Hull fixed a deadlock on MacOS X related to mouse updating.
+
+ Peter Wang fixed a problem with compiling the VBE/AF driver using newer
+ binutils.
+
+ Evert Glebbeek fixed a bug with colour conversions when loading a font from
+ a datafile.
+
+ Many code, example and documentation updates by Grzegorz Adam Hankiewicz,
+ Elias Pschernig, Peter Wang, Evert Glebbeek, Andrei Ellman,
+ Victor Williams Stafusa da Silva, Matthew Leverton, AJ, Michal Molhanec
+ and Hrvoje Ban.
+
+ Grzegorz Adam Hankiewicz did several documentation updates.
+
+ Evert Glebbeek cleaned up some of the global namespace pollution in the
+ Windows port.
+
+ Chris Robinson made improvements to the Windows sound driver.
+
+ Chris Robinson made the GUI multi-selection box behave a bit nicer.
+
+ Grzegorz Adam Hankiewicz added a bunch of ASSERTs to the code to check for
+ out-of-range arguments.
+
+ Jakub Wasilewski fixed a bug when loading greyscale TGA images.
+
+ Evert Glebbeek fixed a bug where the bottom and right line of pixels was
+ not updated on show_video_bitmap, as pointed out by Thomas Harte.
+
+ Evert Glebbeek documented JOY_TYPE_* defines for Windows and Linux.
+
+ Dark Nation restored the ability to read old-style encrypted packfiles,
+ i.e. those produced before Allegro 3.9.30. This was silently removed
+ from 4.1.18 when custom packfile support / decoupled compression routines
+ were added.
+
+ Evert Glebbeek made the grabber and dat utilities now use Allegro's builtin
+ load_font() function and made datafiles properly store truecolour fonts and
+ added a datedit_select() callback to datedit.
+
+ Evert Glebbeek fixed some unsafe assumptions on the size of integer
+ data types.
+
+ Arthur Huillet fixed a typo in the docs.
+
+ Elias Pschernig restored Alt+key = ASCII code 0 behavior for the Windows
+ keyboard driver
+
+ Evert Glebbeek fixed a bug that caused a crash when loading Allegro 1.x
+ datafiles containing 4 bit bitmaps.
+
+ Peter Wang clarified the mode select documentation and made the mode
+ selector clear the input variables before passing them on to the filter.
+
+ Peter Wang fixed a bug in the mode selector where disabled drivers were
+ still shown with empty resolution lists. Pointed out by Hrvoje Ban.
+
+ Elias Pschernig fixed Allegro's internal multithreading in Windows. This
+ fixes a deadlock on exit.
+
+ Robert Alfonso made the MSVC makefile call `link /lib' rather than `lib',
+ which doesn't work for the free toolkit.
+
+ Peter Hull fixed a problem with hardware cursors not working properly in
+ MacOS X.
+
+ Peter Hull added a missing enable_hardware_cursor vtable entry and added OS
+ native cursors for the MacOS X port.
+
+ Grzegorz Adam Hankiewicz documented the online Allegro patch generator.
+
+ Peter Wang fixed many problems on AMD64 in Linux - it should now work fine.
+
+ Peter Hull added CPU detection to the MacOS X port.
+
+ Peter Hull fixed some problems related to /usr/local/bin not existing in
+ recent versions of MacOS X.
+
+ Elias Pschernig and Peter Wang rewrote the Windows keyboard driver so it
+ no longer needs keyboard.dat.
+
+ Elias Pschernig added a show_os_cursor function as an alternative to
+ show_mouse() for system cursors.
+
+ Evert Glebbeek and Peter Wang added an example programme for system cursors.
+
+ Elias Pschernig fixed a deadlocks in X11 related to scare_mouse() and
+ keyboard repeats and fixed async replies.
+
+ Daniel Schlyder fixed the gcc -mcpu is deprecated warnings.
+
+ Peter Wang added an astdint.h, which provides C99 typedefs for pre-C99
+ compilers.
+
+ AJ added detection for DirectX 8 and 9 to the Windows port.
+
+ Evert Glebbeek added detection for AMD64 to the UNIX port and test
+ programme.
+
+ Elias Pschernig added a get_midi_length function and a midi_time variable.
+
+ Elias Pschernig fixed a problem where Allegro would ignore a user-specified
+ configuration file if set_config_file() was called before allegro_init().
+
+ Evert Glebbeek added a transpose_font function.
+
+ Evert Glebbeek added support for true colour fonts and a font example.
+
+ Elias Pschernig fixed a problem in shutdown_dialog() reported by Tobi
+ Vollebregt.
+
+ Marcio Fialho fixed some issues with displaying author names in the demo
+ game.
+
+ Andrei Ellman fixed a problem in the MSVC makefile when building Allegro
+ with Cygwin.
+
+ Daniel Schlyder fixed (again) problems with creating directories in
+ different setups in Windows.
+
+ Elias Pschernig added documentation for the custom packfile functions.
+
+ Jeff Mitchell fixed the location of grabber.txt in the spec file.
+
+ Harshavardhana Reddy added a Kannada greeting to exunicod.
+
+ Elias Pschernig cleaned up the example programmes.
+
+ Peter Wang made it possible to disable the hardware cursor in X by passing
+ an option to the configure script.
+
+ AJ and Michal Molhanec added an MSVC 7 configure option and added an msvc7
+ switch to fix.bat. Karthik Kumar did the same for the Intel compiler icl.
+
+ Mr_Bones fixed compilation of setup.c when --disable-ossdigi is used
+
+ AJ fixed a beep being generated in Windows when alt+character was pressed
+ in Windowed mode.
+
+ Peter Wang fixed many oversights and problems in the library and examples and
+ allowed the code to be build with stricter warnings.
+
+ Peter Wang fixed problems compiling the Windows port with WARNMODE=1
+
+ Tore Halse fixed compilation problems in Windows related to TITLEBARINFO.
+
+ Daniel Schlyder made the Windows port use TITLEBARINFO if it is available.
+
+ Grzegorz Adam Hankiewicz made many improvements to the documentation.
+
+ Elias Pschernig deprecated yield_timeslice in favour of rest(0) and adjusted
+ yield_timeslice on BeOS, QNX and MacOS X to behave the same as on other
+ platforms.
+
+ Eric Botcazou fixed a problem with the asm colour converter.
+
+ Elias Pschernig fixed some gcc warnings.
+
+ Vincent Penquerc'h added the ability to pass extra CFLAGS and LDFLAGS on the
+ make command line.
+
+ Elias Pschernig made ex3buf work outside of DOS.
+
+ Chris Robinson made the alleg mixer default instead of the DirectX one in
+ windows.
+
+ Angelo Mottola fixed a bug where vsync() was blocking on a mutex if called
+ when the screen was already acquired in windowed mode.
+
+ Evert Glebbeek made triple buffering work in the demo if VRAM is a single
+ surface.
+
+ Jon Rafkind provided an m4 macro for Allegro.
+
+ Eric Botcazou and Henrik Stokseth made some improvements to the build
+ process.
+
+ Grzegorz Adam Hankiewicz added various fixes to the documentation and
+ to the documentation generation system.
+
+ V Karthik Kumar added a Tamil language greeting to exunicode.
+
+ Chris Robinson and Elias Pschernig reduced lag under X11 when X11
+ locks are held for too long.
+
+ Vincent Penquerc'h fixed a problem with dependency generation under
+ bash.
+
+ Evert Glebbeek added an icon to the X11 port and contributed the xfixicon
+ script.
+
+ Angelo Mottola fixed an endianess issue when loading/saving 24 bit
+ images from datafiles.
+
+ Angelo Mottola made datafile plugins return FALSE on error.
+
+ Angelo Mottola fixed the docs for pack_putc.
+
+ Vincent Penquerc'h made the grabber choose better default menu
+ shortcuts.
+
+ Henrik Stokseth enabled the asm color converters for the X11 port.
+
+ Henrik Stokseth improved buffer security in various parts of the
+ library.
+
+ Evert Glebbeek made strncpy use sizeof() for fixed length strings.
+
+ Eric Botcazou made KEY_PAUSE work properly in windows.
+
+ Chris Robinson improved the threaded UNIX timer code.
+
+ Elias Pschernig fixed some problems with the ALSA driver.
+
+ Angelo Mottola made Command-Q and Quit trigger the
+ close_button_callback in OSX.
+
+ Grady Martin fixed a bug in the handling of %n in the printf style
+ text functions.
+
+ Chris Robinson rewrote parts of Allegro's mixer.
+
+ Chris Robinson increased the default volume, which was set very quiet
+ previously.
+
+ Grzegorz Adam Hankiewicz clarified the behavior of install_mouse.
+
+ Elias Pschernig improved the pause key behavior.
+
+ Vincent Penquerc'h added MSG_WANTMOUSE to the GUI.
+
+ Vincent Penquerc'h sped up get_filename.
+
+ Chris Robinson implemented the digmid_set_pan function
+
+ Chris Robinson improved the performance of the DIGMID driver.
+
+ Minor changes and clarifications in the docs by Sven Sandberg, Andy Goth,
+ Jon Rafkind, Nathan Smith and Daniel Schlyder.
+
+ Elias Pschernig extensively modified the ALSA 0.9/1.0 sound driver to make
+ it work more nicely.
+
+ Julien Cugniere and Eric Botcazou fixed the crash on exit with the aRts
+ sound driver.
+
+ Nathan Smith implemented the recursive handling of directories for the
+ dat utility.
+
+ Eric Botcazou renamed the new '-r' option of the dat utility into '-f'.
+
+ Omar Cornut improved the handling of KEY_COLON2 on Japanese keyboards.
+
+ Omar Cornut fixed the Windows joystick driver to handle a weird peculiarity
+ of the DirectInput API.
+
+ Elias Pschernig corrected the value of the alpha-channel depth field in the
+ header when saving TGA image files.
+
+ Eric Botcazou fixed again the formula giving the stride value in the Linux
+ framebuffer console.
+
+ Eric Botcazou restored the pixel-correct version of line() and added
+ fastline() after Doug Eleveld had reported the problem.
+
+ Andy Goth and Eric Botcazou fixed the constructor support in dat2s on Unix.
+
+ Angelo Mottola revamped the MacOS X package creation process to make it
+ work under 10.3 and create an enduser package that holds just the shared
+ framework.
+
+ Angelo Mottola changed the MacOS X shared library building process to have
+ a prebound shared library separated from a small static libray holding just
+ the magic main stuff.
+
+ Angelo Mottola removed window shadow flickering when moving the program
+ window around on MacOS X.
+
+ Elias Pschernig changed the behavior of yield_timeslice() to sleeping
+ instead of just yielding.
+
+ Angelo Mottola made the MacOS X port reuse the screen on the first video
+ bitmap creation and made the screen fade on mode switches faster.
+
+ Elias Pschernig made d_menu_proc() automatically yield when the dialog
+ is driven by do_dialog().
+
+ Elias Pschernig added missing d_yield_proc()s to the grabber.
+
+ Eric Botcazou fixed a bug which caused too many sliders to be reported
+ in the presence of a POV device on Windows.
+
+ Chris Jones added support for the bitfield compressed BMP image format.
+
+ Eric Botcazou removed all uses of GCC's cast-expression-as-lvalue
+ extension in preparation for GCC 3.4.
+
+ Michal Molhanec replaced all occurences of MingW32 by MinGW in the docs.
+
+ Omar Cornut bumped the maximum number of buttons per joystick to 32.
+
+ Eric Botcazou implemented automatic screensaver disabling (only on
+ Windows for the time being).
+
+ Elias Pschernig added mode 1280x960 to the gfx mode selector.
+
+ Elias Pschernig fixed the video mode error display in the test program.
+
+ Eric Botcazou fixed the final animation of the demo game.
+
+ Elias Pschernig made the X11 gfx driver ignore repeated key-events.
+
+ Eric Botcazou added set_hardware_volume().
+
+ Francisco Pires added an FPS counter and an option to disable vsync to
+ the excamera example.
+
+ Eric Botcazou and Sven Sandberg documented the limitations of getpixel()
+ and added is_inside_bitmap().
+
+ Eric Botcazou added i386 sincos optimization to GCC-based ports.
+
+ David Capello fixed a bug with FLI frames containing odd-sized chunks.
+
+ Elias Pschernig and Sven Sandberg improved the GUI focus algorithm.
+
+ Eric Botcazou modified the dat/grabber plugins interface to expose
+ datafile properties to plugins.
+
+ Eric Botcazou added a new clipping API and deprecated the old one.
+
+ Grzegorz Adam Hankiewicz updated the MSVC build instructions.
+
+ Many minor changes and clarifications in the docs, some of them based on
+ suggestions by Neil Roy, Jon Rafkind, aj, Andrei Ellman and Michal
+ Molhanec.
+
+ Angelo Mottola made little fixes all over the place in the MacOS X port.
+
+ Angelo Mottola removed MacOS X 10.1.x source compatibility.
+
+ Eric Botcazou disabled keyconf on platforms that don't need it.
+
+ Elias Pschernig shifted key name display so that all keys are visible
+ in the keyconf utility.
+
+ Stephan Brauss added new keysyms to the X11-to-BIOS conversion table in
+ order to catch missing keycodes for the keypad when NumLock is on.
+
+ Stephan Brauss corrected a few nits in the Swiss keyboard configuration
+ file.
+
+ Eric Botcazou disabled the close button support when a user window is
+ registered under Windows.
+
+ Eric Botcazou changed the default switch mode to SWITCH_BACKGROUND for
+ the Windows port to cure the problems on exit under WinXP.
+
+ Sven Sandberg improved the previous fix to _parallelogram_map().
+
+ Sven Sandberg fixed an overflow in floodfill().
+
+ Sven Sandberg fixed the dither blit mode for the Mode-X driver.
+
+ Angelo Mottola added quality and reverberation settings support to the
+ CoreAudio MIDI driver under MacOS X.
+
+ Angelo Mottola added high performance CoreAudio digi/midi drivers (default
+ on autodetect) and made little fixes to the old QT Note Allocator and
+ Carbon Sound Manager drivers under MacOS X.
+
+ KronomanX added a FAQ entry about the conflict between Allegro headers and
+ the C++ 'using' directive.
+
+ Vincent Penquerc'h let dialog_message() pass user messages to hidden
+ objects.
+
+ Michal Molhanec simplified the build instructions for Dev-C++.
+
+ Annie Testes fixed a redrawing problem in the grabber.
+
+ Vincent Penquerc'h added support for the joystick_device* config variables
+ under Linux.
+
+ Vincent Penquerc'h added gfx_mode_select_filter().
+
+ Peter Wang removed the old Linux async I/O stuff, which had been out of
+ service for a long, long time. Also simplified the Linux standard drivers
+ stuff.
+
+ Thomas Fjellstrom added (experimental) support for ALSA 0.9.x.
+
+ John Utz corrected a wrong assumption about the VRAM layout in the Linux
+ framebuffer console driver.
+
+ Grzegorz Adam Hankiewicz tt-ized text quotes in the HTML version of the
+ docs.
+
+ Eric Botcazou made the Linux port compile on non-x86 platforms.
+
+ Stephan Brauss made a few fixes to let the Linux port compile again on
+ Linux 2.2.x systems.
+
+ Kalle Toivonen fixed a bug in _parallelogram_map().
+
+ Eric Botcazou cleaned up the ALSA config variables under Unix.
+
+ David Cullen added multiple bullets and extra lives to the demo game.
+
+ Sam Hocevar fixed a race condition in the mixer under Unix w/ threads,
+ Windows, BeOS and MacOS X.
+
+ Andrei Ellman improved the Windows screensaver.
+
+ Jon Rafkind implemented the Cohen-Sutherland clipping algorithm for the
+ line() function.
+
+ Angelo Mottola added an application menu with a Quit item acting like the
+ three fingers salute, in order to better integrate Allegro apps with the
+ Aqua UI guidelines under MacOS X.
+
+ Jon Rafkind and Vincent Penquerc'h added more ASSERTs to the code.
+
+ Eric Botcazou added an option to disable vsync when page-flipping.
+
+ Eric Botcazou added the detection of spaces to the MSVCDir variable for
+ the MSVC port.
+
+ Grzegorz Adam Hankiewicz integrated the build instructions in the HTML
+ version of the documentation.
+
+ Angelo Mottola fixed some nits in fixbundle for alpha channel on 32-bit
+ icons under MacOS X.
+
+ Lisa Parratt improved the performances of the SGI audio driver.
+
+ Grzegorz Adam Hankiewicz updated and improved the documentation in many
+ places.
+
+ Grzegorz Adam Hankiewicz added HTML text substitution to the doc processor.
+
+ Tobi Vollebregt spotted a bug in ustrerror(), which was not returning a
+ pointer to a static buffer.
+
+ Grzegorz Adam Hankiewicz added more documentation about return values
+ of functions.
+
+ Grzegorz Adam Hankiewicz added a new section about documentation to
+ ahack._tx.
+
+ Grzegorz Adam Hankiewicz fixed rare buffer overflows in do_uconvert with
+ very tiny buffer sizes.
+
+ Serge Semashko fixed a bug with the letter P in the Russian keyboard
+ configuration file.
+
+ Angelo Mottola let application bundles accept files dragged onto the
+ application icon under MacOS X.
+
+ Peter Wang fixed save_bmp for better conformance (a couple of header
+ fields were wrong, and dots-per-metre fields were being filled with zero).
+
+ Julien Cugniere fixed a bug related to the retrieval of the inital volume
+ when no primary buffer was present under Windows.
+
+ Henrik Stokseth simplified the asm detection test, removed many GNUish
+ preprocessor constructs in the asm files and, as a consequence, let the
+ Watcom port use its own preprocessor on assembly files.
+
+ Peter Wang prevented non-mmapped memory from being munmapped under Linux.
+
+ Annie Testes prevented __al_linux_shutdown_vga_helpers from being called
+ unless the corresponding init function was first called under Linux.
+
+ Sven Sandberg improved the misc/findtext.sh script.
+
+ Sven Sandberg added support to produce a PDF version of the manual under
+ Unix and to compress the various formats with bzip2.
+
+ Sven Sandberg made some correction to the Swedish translation file.
+
+ Eric Botcazou pluginized the new 'Change filename' menu option in the
+ grabber.
+
+ Eric Botcazou fixed the X11 mouse scrolling bug.
+
+ Vincent Penquerc'h made it so that modifications to the type or color
+ depth of an image are detected as such by the grabber.
+
+ Henrik Stokseth added a C++ test, Eric Botcazou integrated it in the build
+ process.
+
+ Angelo Mottola made several fixes to let Allegro play nice with AllegroGL
+ under MacOS X.
+
+ Angelo Mottola added proper embeddable framework support to the MacOS X
+ port, modified fixbundle and updated the docs accordingly.
+
+ Angelo Mottola made external plugins scripts work under MacOS X.
+
+ Eric Botcazou temporarily reverted the fix for the mouse bug when
+ scrolling with the X11 driver under Unix.
+
+ Eric Botcazou fixed the invocation of non-GNU make in the configure script,
+ a few compilation warnings in tools/dat2c.c and made it possible to pass
+ libraries to the misc/deplexe.sh script, so as to let Allegro build again
+ under Solaris.
+
+ Grzegorz Adam Hankiewicz removed all direct references to Canvaslink and
+ credited SourceForge for current services.
+
+ Eric Botcazou reworked the configure check for sched_yield() under Unix.
+
+ Sam Hocevar fixed a Bashism in fix.sh that makes Solaris' sh choke.
+
+ Angelo Mottola made sure mouse buttons are initialized to 0 at startup
+ under MacOS X.
+
+ Eric Botcazou added a blurb about the new behaviour of d_ctext_proc().
+
+ Eric Botcazou corrected several inadequacies in the documentation of
+ makefile targets.
+
+ Grzegorz Adam Hankiewicz did some housekeeping work in the docs.
+
+ Angelo Mottola added a missing item to the list of installed files
+ under MacOS X.
+
+ Angelo Mottola added a script to automate the enduser MacOS X package
+ creation.
+
+ Angelo Mottola made it possible to compile apps if just the Allegro
+ framework is installed under MacOS X.
+
+ Vincent Penquerc'h corrected an inefficiency in select_palette() and
+ unselect_palette().
+
+ Eric Botcazou fixed the build failure with MSVC.
+
+ Andrei Ellman added a few missing items to the list of uninstalled files
+ for the MinGW and MSVC ports.
+
+ Vincent Penquerc'h fixed a bug in _fill_3d_edge_structure().
+
+ Many minor changes and clarifications in the docs.
+
+ Hein Zelle reworked the paragraph on the location of shared libraries
+ under Unix in the docs and added a FAQ entry on the same subject.
+
+ Martijn Van Lersel fixed an overflow in create_light_table().
+
+ Chris Jones and Eric Botcazou made the MIDI player handle the 'All Sound Off'
+ controller message.
+
+ Angelo Mottola made the MacOS X port play nice with 10.1.x.
+
+ Eric Botcazou made the menus not block on exit when mouse buttons are
+ still being held down.
+
+ Grzegorz Adam Hankiewicz improved the description of set_gfx_mode about
+ virtual screen sizes and hardware scrolling by suggestion of Lothar May.
+
+ Chris Jones let the MIDI player pass controller events to the raw player
+ by default.
+
+ Angelo Mottola added the platform-dependent AL_RAND() macro.
+
+ Angelo Mottola added a HID joystick driver to the MacOS X port.
+
+ Henrik Stokseth spotted non-standard constructs in the Windows port.
+
+ Henrik Stokseth spotted unused variables throughout the library.
+
+ Jim Grainger spotted a broken link in the docs and updated it.
+
+ Javier Gonzalez fixed some problems in the DirectSound streaming.
+
+ Andrei Ellman improved the exrgbhsv example.
+
+ Andrei Ellman corrected a rounding issue in hsv_to_rgb().
+
+ Angelo Mottola added _al_rand() and replaced rand() with it throughout
+ the library.
+
+ Elias Pschernig moved the big font example from exgui to excustom and
+ fixed d_edit_box string length.
+
+ Angelo Mottola added the 'fixbundle' utility to the MacOS X port.
+
+ Eric Botcazou added the possibility to fold/unfold nested datafiles in
+ the grabber.
+
+ Angelo Mottola fixed a couple of color conversion bugs.
+
+ Elias Pschernig replaced exgui with a more thorough version.
+
+ Vincent Penquerc'h added support for debugging with Fortify under Unix.
+
+ Vincent Penquerc'h added the 'Replace' option to the grabber.
+
+ Vincent Penquerc'h added the 'Force Update Selection' command to the
+ grabber and refactored a fair amount of duplicated code.
+
+ Eric Botcazou made exunicod endian-safe.
+
+ Eric Botcazou fixed the behaviour of the C version of draw_trans_sprite()
+ with 32-bit RGBA sprites.
+
+ Angelo Mottola fixed the behaviour of the C version of draw_trans_sprite()
+ in 8bpp mode.
+
+ Angelo Mottola added system bitmaps support to the MacOS X port.
+
+ Eric Botcazou enabled full support of relative filenames in the dat/grabber
+ utilities.
+
+ Angelo Mottola made exlights endian-safe.
+
+ Christer Sandberg fixed a bug in the 24-bit graphics code of fixup_datafile().
+
+ Angelo Mottola added hw-accelerated VRAM->VRAM blit support under MacOS X.
+
+ Angelo Mottola added an install-template makefile target to install an
+ Allegro application Project Builder template under MacOS X.
+
+ Angelo Mottola added a digital sound driver to the MacOS X port.
+
+ John Holden fixed a bug in load_wav().
+
+ Angelo Mottola added a MIDI driver to the MacOS X port.
+
+ Angelo Mottola added proper mouse buttons detection via HID Manager and
+ buttons emulation if needed under MacOS X.
+
+ Eric Botcazou added canonicalize_filename() and deprecated fix_filename_path().
+
+ Evert Glebbeek added the support for relative filenames to the grabber.
+
+ Eric Botcazou made it possible to pass CC on the command line to make
+ on non-Unix systems.
+
+ Angelo Mottola added support for bundled applications under MacOS X.
+
+ Javier Gonzalez devised a simpler fix for the WinXP black screen bug.
+
+ Javier Gonzalez prevented some artifacts from being left on the screen
+ when moving fast the window under Windows.
+
+ Angelo Mottola contributed the MacOS X port.
+
+ Angelo Mottola fixed various things in preparation for the MacOS X port.
+
+ Eric Botcazou uncoupled link options for libraries and programs.
+
+ Evert Glebbeek added the support for relative filenames by means of three
+ new API functions.
+
+ Elias Pschernig made the allegro.devhelp work with devhelp 0.6.0.
+
+ Eric Botcazou made file_select_ex() honor the '(+)d' attribute character
+ in the extension string.
+
+ Eric Botcazou removed the remaining occurences of ustrcpy() from the
+ library code.
+
+ Christer Sandberg fixed a problem with the include guard generated
+ by dat2c.
+
+ Eric Botcazou removed the remaining calls to deprecated functions from
+ the distribution.
+
+ Eric Botcazou optimized the handling of the extension string in the
+ file selector.
+
+ Eric Botcazou implemented the AL_*_DEPRECATED macros and enabled them
+ for GCC 3.1 or later.
+
+ Sven Sandberg improved the performance of the rgb_to_hsv() function.
+
+ Christer Sandberg and Eric Botcazou made dat2c correctly detect the
+ native line ending.
+
+ Christer Sandberg and Eric Botcazou made dat2c work better with ISO C90
+ compilers.
+
+ Henrik Stokseth updated the installation and configuration instructions
+ of both MinGW and Dev-C++ and documented the support of MSYS.
+
+ Andrei Ellman improved the performance of the hsv_to_rgb() function.
+
+ Peter Wang made the makefile not pass the -s switch to ld on Unix for
+ non-optimized builds.
+
+ Evert Glebbeek added the 'New' command to the grabber.
+
+ Eric Botcazou made the grabber save previous modified data when loading
+ new data.
+
+ Eric Botcazou unified and fixed the support for ALLEGRO_USE_C on all
+ GCC-based ports.
+
+ Eric Botcazou unified the autodetection and handling of Unix-like tools
+ on non-Unix systems.
+
+ Andrei Ellman got Allegro for MSVC to build with Cygwin.
+
+ Elias Pschernig made the programs be linked with -pg in profile mode
+ under Unix.
+
+ Andrei Ellman updated the Cygwin section in docs/build/mingw32.txt.
+
+ Magnus Henoch fixed a problem when compiling without 8bpp support.
+
+ James Ponder and Hein Zelle clarified a requirement when cross-compiling
+ from Linux.
+
+ James Ponder suggested to remove the DJGPP makefile from the Unix tar
+ archive.
+
+ Grzegorz Adam Hankiewicz improved the docs on allegro_exit().
+
+ Grzegorz Adam Hankiewicz documented the bunch of packfile functions.
+
+ Eric Botcazou fixed the profile build on BeOS.
+
+ Eric Botcazou updated the FAQ about DJGPP's va_list problem (thanks
+ to aj for spotting this).
+
+ Andrei Ellman suggested some additions to the docs.
+
+ Grzegorz Adam Hankiewicz added a chapter on available examples to the
+ docs, the ability to cross-reference them and display the references
+ with a specific layout in the HTML docs, and a Python script to automate
+ the updating process when new examples are added.
+
+ Eric Botcazou fixed an asm locking bug under Windows spotted by
+ Omar Cornut.
+
+ EvilTypeGuy cleaned up and fixed the RPM spec file for RedHat 9.
+
+ Ville Skyttä fixed a problem with make install libdir= and modules on
+ Unix systems.
+
+ Peter Wang added a hack to not unload the SVGAlib module if SVGAlib
+ installs an atexit() handler.
+
+ Elias Pschernig updated xf2pcx and integrated it in the build process
+ under Unix/X11.
+
+ Grzegorz Adam Hankiewicz added support for dumping the configure settings
+ under Unix.
+
+ Javier Gonzalez added get_color_depth() to the API.
+
+ Julien Cugniere and Eric Botcazou improved the support for non-blocking
+ menus.
+
+ Grzegorz Adam Hankiewicz corrected several nits in the documentation.
+
+ Grzegorz Adam Hankiewicz documented the END_OF_MAIN macro.
+
+ Javier Gonzalez added get_color_conversion() to the API.
+
+ Lennart Steinke added the exconfig example.
+
+ Eric Botcazou added big-endian support to the BMP, PCX and TGA loaders
+ as well as to the X11 driver.
+
+ Eric Botcazou fixed the 'uninstall' target and a problem with
+ Mingw32's make for the Watcom port.
+
+ Charles Bilyue suggested to not force yielding timeslice with non-blocking
+ menus.
+
+ Annie Testes fixed a bug with asynchronous I/O mode restoring under Linux.
+
+ Annie Testes made the screen be cleared before setting the default
+ palette when calling set_gfx_mode().
+
+ Annie Testes fixed a bug with patterned drawing in the C version.
+
+ Vincent Penquerc'h spotted an off-by-one problem when building the list
+ of color depths in the gfx mode selector.
+
+ Peter Wang made the Intellimouse PS/2 driver work for USB mice in Linux.
+
+ Elias Pschernig integrated xkeymap in the build process under Unix/X11.
+
+ Oscar Giner fixed a conflict between the magic main and the MFC.
+
+ Matthew Leverton fixed a bug with pack_fgets().
+
+ Eric Botcazou fixed broken and missing dependencies for make -j2 builds.
+
+ Hein Zelle revamped the cross-compilation section of docs/build/mingw32.txt.
+
+ Marcel Smit and Eric Botcazou made the show_video_bitmap() method of the
+ Windows windowed driver wait for a vsync.
+
+ Eric Botcazou made the test program really time the fixed math functions.
+
+ Eric Botcazou clarified the limitations of Allegro's interrupts regarding
+ the FPU state under DOS.
+
+ Peter Wang fixed a bug in stretch_blit() where the first column or row can
+ get an extra pixel, reported by David Gowers and AJ.
+
+ Eric Botcazou made the linux mouse detection code really empty the buffer
+ before proceeding in the setup program.
+
+ Eric Botcazou made the Watcom port compile in warnmode with Open Watcom.
+
+ Elias Pschernig fixed the build with the Unix->MinGW cross-compiler.
+
+ Magnus Henoch made the gfx mode selector keep the current selection as
+ much as possible.
+
+ Eric Botcazou fixed the mouse not being scared over alert boxes.
+
+ Eric Botcazou added -Wstrict-prototypes to the build warnmode under DOS,
+ Windows and BeOS.
+
+ Annie Testes updated the mouse autodetection code under Linux to take
+ into account her EVDEV driver.
+
+ Philipp Thomas added multi-arch support, DESTDIR support and the German
+ translation to the RPM spec file.
+
+ Philipp Thomas converted the configure machinery to autoconf 2.53 or later.
+
+ Philipp Thomas fixed all function prototypes, thus allowing to build with
+ -Wstrict-prototypes on Unix systems.
+
+ Philipp Thomas fixed the compilation on x86-64.
+
+ Philipp Thomas fixed all comparisons between signed and unsigned types,
+ thus allowing to build with -W -Wno-unused on Unix systems.
+
+ Eric Botcazou reworked the truecolor subsection of the 'Transparency and
+ patterned drawing' section.
+
+ Eric Botcazou clarified the return value on failure of file_time(),
+ following AJ's suggestion.
+
+ Eric Botcazou fixed the build in strictwarn mode on Unix systems.
+
+ Eric Botcazou fixed a mouse bug when the screen is scrolled with the X11
+ fullscreen driver.
+
+ Eric Botcazou fixed a bug with resolution and color depth not being taken
+ into account by gfx_mode_select_ex().
+
+ Vincent Penquerc'h fixed the compilation breakage on Linux kernels 2.2.x.
+
+ Eric Botcazou defined ALLEGRO_LIB_BUILD for debug and profile releases as
+ well on Unix systems.
+
+ Eric Botcazou forced the exstream example to abort if no real sound driver
+ is found.
+
+ Eric Botcazou clarified the limitations of the stretching functions.
+
+ Acho A. Tang added a Sidewinder Precision Pro joystick driver to the
+ DOS port.
+
+ Eric Botcazou re-enabled the autodetection of joysticks in the setup
+ program.
+
+ Many minor changes and clarifications in the docs.
+
+ Annie Testes fixed some device name strings in the setup program.
+
+ Annie Testes added a mouse driver based on the event interface (EVDEV)
+ to the Linux port.
+
+ Eric Botcazou added for_each_file_ex() and deprecated for_each_file().
+
+ Eric Botcazou disabled hackish centering code in fullscreen mode
+ under X11 which caused some artifacts to appear on KDE desktops.
+
+ Elias Pschernig fixed a pasto in the sample reading code.
+
+ Eric Botcazou fixed a bug with Alt+TAB under X11.
+
+ Eric Botcazou added a configure check for the include prefix problem
+ with gcc 3.1 or later on Unix systems.
+
+ Eric Botcazou reverted the latest patch applied to the joystick code.
+
+ Matt Witherspoon and Eric Botcazou fixed a bug in the scroll() method of
+ the Linux SVGAlib driver so as to make it wait for the vertical retrace.
+
+ Eric Botcazou added a stop/resume option to the exstream.c example.
+
+ Ben Davis documented the non-standard behaviour of pack_feof().
+
+ Eric Botcazou worked around a weird problem with some X11 window managers
+ that prevented the fullscreen driver from setting up.
+
+ Eric Botcazou disabled the new timer synchronization code.
+
+ Grzegorz Adam Hankiewicz added a warning about DJGPP stability under some
+ Windows versions.
+
+ Eric Botcazou made it so that the window is centered at startup under
+ Windows.
+
+ Chris Jones and Eric Botcazou worked around a problem with DOS file
+ attributes under Win2k.
+
+ Eric Botcazou made the filetest work better with the keyboard.
+
+ Eric Botcazou fixed shifted help sections in the grabber.
+
+ Eric Botcazou fixed the mishandling of TAB characters in menu bar entries.
+
+ Eric Botcazou added a new DEBUGMODE level so that debuggers will not be
+ flooded by internal debug messages any more under Windows.
+
+ Eric Botcazou fixed a weird compilation bug under MacOS X.
+
+ Grzegorz Adam Hankiewicz updated the docs about mailing lists/contacts.
+
+ Grzegorz Adam Hankiewicz added instructions on how to create and submit
+ patches to the Allegro developers.
+
+ Eric Botcazou implemented the support for non-blocking menus.
+
+ Lisa Parratt spotted a BSDism that IRIX doesn't like at all.
+
+ Daniel Schlyder fixed a problem with set_window_title() under BeOS.
+
+ Lisa Parratt contributed the SGI Audio Library sound driver.
+
+ Eric Botcazou completely revamped the close button support.
+
+ Eric Botcazou simplified fullscreen mode initialization under Windows.
+
+ Elias Pschernig and Eric Botcazou made the GUI code scare the mouse, when
+ drawing, only if it is necessary to do so, thus reducing cursor flicker.
+
+ Eric Botcazou fixed a bug in scare_mouse_area().
+
+ Elias Pschernig optimized the load_bitmap() function family when no
+ palette is specified and documented the feature.
+
+ Grzegorz Adam Hankiewicz aliased the stylesheet to the default CSS style,
+ allowing The Big Lizard(tm) and other web browsers to disable CSS.
+
+ Eric Botcazou fixed an ill-behaviour at startup under Windows.
+
+ Elias Pschernig added the Euro character to the default font and to the
+ German and French keyboard configuration files.
+
+ Eric Botcazou made _ustrdup() set *allegro_errno to ENOMEM on failures.
+
+ Annie Testes lifted several hardcoded length limitations in the
+ configuration routines.
+
+ Eric Botcazou prevented set_gfx_mode() from resetting the layout of all
+ color depths.
+
+ Eric Botcazou moved #include directives out of the range of extern "C"
+ directives (fixing the C++ compilation bug with Borland C++).
+
+ Vincent Penquerc'h added the ALLEGRO_NO_COMPATIBILITY symbol and moved
+ all the deprecated stuff from allegro._tx to api._tx .
+
+ Grzegorz Adam Hankiewicz reformatted monospaced text blocks to fit page
+ in Postscript output.
+
+ Oscar Giner added the Catalan translation.
+
+ Oscar Giner corrected the Spanish translation.
+
+ Grzegorz Adam Hankiewicz added a new command to the doc processor for
+ email mangling: me@serv.com -> me at serv dot com. It is applied to all
+ documentation output formats.
+
+ Grzegorz Adam Hankiewicz made all source files use the external CSS.
+
+ Chris Jones fixed a bug with 16-bit samples loading introduced in the
+ previous release.
+
+ Eric Botcazou prevented the linker from choking on Solaris because of a
+ static library with no symbols.
+
+ Eric Botcazou removed joystick control from main part of the setup program.
+
+ Eric Botcazou documented the workaround needed for C++ programs compiled
+ with Borland C++ (in docs/build/bcc32.txt).
+
+ Eric Botcazou unified the magic main for the 3 Windows compilers and fixed
+ the WinMain() linkage for Borland C++.
+
+ Henrik Schmidt made gcc pass '-h' instead of '-soname' to the linker and
+ replaced '-L' by '-h' in shell comparisons so as not to break on Solaris.
+
+ Eric Botcazou fixed the bogus check for GNU ar on Unix systems.
+
+ Elias Pschernig made load_datafile_object() load the properties attached
+ to the object.
+
+ Javier Gonzalez and Eric Botcazou fixed the infamous blank screen problem
+ under Win2k/WinXP.
+
+ Eric Botcazou cleaned up the use of errno/allegro_errno throughout the
+ library and removed all occurences of errno in the grabber/plugins code.
+
+ Grzegorz Adam Hankiewicz embedded readme.txt into the Allegro manual.
+
+ Eric Botcazou made the Windows port set the NULL mouse cursor in
+ fullscreen mode instead of hiding it.
+
+ Vincent Penquerc'h ASSERTed a bunch of C drawing routines.
+
+ Robert J. Ohannessian did some cosmetic improvements to the HTML output
+ and separated the CSS file.
+
+ Evert Glebbeek added configure options for x86 processor optimizations
+ on Unix systems.
+
+ Benny Colyn added a Dutch translation.
+
+ Evert Glebbeek added the detection of SunOS/Solaris.
+
+ Javier Gonzalez fixed a graphics bug with always-on-top applications.
+
+ Igor Gnip added the detection of MSYS via the SHELL variable to the
+ MingW32 port.
+
+ Eric Botcazou made the mouse use the exclusive foreground cooperative
+ level in fullscreen mode under Windows.
+
+ Eric Botcazou fixed a bug than had prevented ALT+F4 from being properly
+ handled under Windows and cleaned up the low-level scancode handler.
+
+ Eric Botcazou updated the description of the layout of header files in
+ the aHack file.
+
+ Grzegorz Adam Hankiewicz corrected the docs about 'ulimit' in the Help
+ file.
+
+ Laurence Withers converted the core library and the whole distribution
+ to use the new text API.
+
+ Laurence Withers added a new text API and deprecated the old one.
+
+ Eric Botcazou made the Windows port stop triggering SWITCH_IN events
+ when restoring the DirectDraw surfaces.
+
+ Eric Botcazou re-enabled screensavers and powerdowns under Windows.
+
+ Eric Botcazou made the deprecated file_select() an inline function.
+
+ Eric Botcazou cleaned up set_gfx_mode() and made it so that GFX_SAFE
+ selects a windowed mode in windowed environments.
+
+ Vincent Penquerc'h added a container header file graphics.h for all the
+ graphics stuff.
+
+ Vincent Penquerc'h added an indexing option to the grabber.
+
+ Evert Glebbeek added an option menu to the grabber.
+
+ Evert Glebbeek and Eric Botcazou cleaned up the grabber/plugins code;
+ in particular, the 'save' method of plugins got a new prototype.
+
+ Peter Wang made fix.sh and zipup.sh not destroy timestamps when just
+ changing EOL markers.
+
+ Peter Wang fixed a misuse of the -I option with gcc 3.0 and later.
+
+ Robert J. Ohannessian added more caveats to docs/build/mingw32.txt.
+
+ Many minor changes and clarifications in the docs and the FAQ.
+
+ Eric Botcazou fixed a bug with graphics mode switching using a
+ ALT+key combination under Windows.
+
+ Laurence Withers contributed the dat2c utility.
+
+ Grzegorz Adam Hankiewicz made it so that chapters can be referenced
+ in the documentation and added a new one on the types and
+ structures defined by the library.
+
+ Eric Botcazou improved win_set_window() so that it can be called
+ after the library has been initialized.
+
+ Elias Pschernig fixed a bug in midi_seek().
+
+ Eric Botcazou wrote a new page flipping/triple buffering code for the
+ Windows port.
+
+ Grzegorz Adam Hankiewicz added a linux specific debug help section.
+
+ Eric Botcazou made the constructors of the fix class from integer and
+ floating point values explicit.
+
+ Eric Botcazou fixed a dat2s bug with dynamically linked programs
+ under Windows.
+
+ Jan Bruun Andersen fixed a compilation problem with Cygwin.
+
+ Jeremiah Blanchard updated the build instructions for Darwin.
+
+ Vincent Penquerc'h added sample loader/saver registration and a
+ save_sample() function. Peter Wang documented it.
+
+ George Foot added (preliminary) non-FM support to the OSS MIDI driver.
+
+ Ben Davis and Robert J. Ohannessian put in (void *) casts for the
+ LOCK_* macros on DJGPP and Mac.
+
+ Nicholas Davies made the fix class not trigger warnings with gcc -Weffc++.
+
+ Angelo Mottola fixed a keyboard focus problem under BeOS.
+
+ Peter Wang fixed the detection of ESD and aRts on Unix systems.
+
+ Peter Wang made files be opened with as permissive as possible
+ permissions on Unix systems.
+
+ Stepan Roh added support for a automake-style DESTDIR variable in the
+ Unix makefile.
+
+ Grzegorz Adam Hankiewicz made the doc processor output valid HMTL 4.0 in
+ some corner cases for which it previously didn't.
+
+ Grzegorz Adam Hankiewicz fixed a crash of the doc processor with very
+ long lines.
+
+ Peter Wang did some housekeeping work throughout the code and the
+ documentation.
+
+ Many minor changes, many clarifications in the docs.
+
+ Peter Wang fixed the installation of shared libs under FreeBSD.
+
+ Peter Wang and Eric Botcazou fixed autodetection glitches for VGA and
+ SVGAlib.
+
+ Eric Botcazou fixed a problem under X11 when the MIT X-SHM extension is
+ used.
+
+ Eric Botcazou fixed a deadlock on exit when an user window is used in
+ conjunction with timers under Windows.
+
+ Eric Botcazou disabled useless backbuffers for the DirectX safe driver.
+
+ Peter Wang made the Alsa sound driver use non-blocking mode when
+ detecting if ALSA PCM available.
+
+ Sven Sandberg added support for long long integers to usprintf() and al.
+
+ Robert J. Ohannessian fixed the difference blender.
+
+ Peter Wang fixed a race condition when closing the X display.
+
+ Elias Pschernig made all active dialogs redraw themselves after a switch.
+
+ Peter Wang made fbcon a priority driver, so that it can appear above VGA.
+
+ Javier Gonzalez fixed a glitch in the DirectSound input code.
+
+ Eric Botcazou fixed the SIGSEGV on exit with the three-finger salute
+ under QNX.
+
+ Eric Botcazou fixed the C-to-asm calling problem for Borland C++ compiled
+ programs.
+
+ Eric Botcazou cleaned up the messy (and somewhat incorrect) DirectDraw
+ bitmap management code.
+
+ Sven Sandberg improved the video bitmap subdivision algorithm.
+
+ Sven Sandberg fixed problems in the Windows makefiles (especially
+ Borland) when building Allegro under Win98.
+
+ Peter Wang removed the hack which switched off fix aliases under IRIX.
+
+ Vincent Penquerc'h fixed a problem with the SIGALRM timer and
+ SWITCH_PAUSE.
+
+ Javier Gonzalez fixed a latency problem with audiostreams.
+
+ Laurence Withers made the font exporter use the current palette for the
+ output.
+
+ Elias Pschernig made some changes to grabber: added a close hook; keeps
+ track if anything has been modified; when you exit the grabber and the
+ file was modified, the popup now has a 3rd option for save+exit; window
+ title displays the current filename, and if the file has been modified;
+ fixed multicolour font exports.
+
+ Sven Sandberg optimized again the create_light_table() function.
+
+ Attila Szilagyi fixed SVGAlib horizontal scrolling.
+
+ Eric Botcazou fixed synchronization problems under QNX.
+
+ Grzegorz Adam Hankiewicz made the TOC at the top of sections
+ alphabetically sorted.
+
+ Eric Botcazou fixed the screen not restored after a wake-up in the
+ Windows windowed and overlay drivers.
+
+ Richard Reeve fixed a silly mistake with gcc 3.0.x detection.
+
+ Angelo Mottola fixed static keyconf compilation problem on BeOS due to
+ pckeys keyboard driver.
+
+ Eric Botcazou fixed the not-returning-focus-on-exit bug under Windows.
+
+ Michael Bukin fixed a bug with C-version textprintf on 24-bpp bitmaps,
+ reported by Bertrand Coconnier.
+
+ Eric Botcazou fixed a bug in the 32->15 MMX color conversion routine.
+
+ Eric Botcazou fixed the DLL linking problem with Borland C++ Builder 4.
+
+ Sven Sandberg made exaccel more responsive.
+
+ Sven Sandberg fixed a glitch with short filenames under DOS.
+
+ Eric Botcazou modularised the VGA/Mode-X drivers under Linux.
+
+ Peter Wang fixed the segfault bug in Mode-X under Linux with threads.
+
+ Peter Wang made the X11 port use SIGTERM signal instead of exit() when
+ invoking the three finger salute. This solves a problem where programs
+ with sound hang when they are killed.
+
+ Eric Botcazou added os_version and os_revision support to the QNX port and
+ added a QNX specific section to the docs.
+
+ Peter Wang added a deadzone for digital readings of joystick axes under
+ Linux, as suggested by George Foot and made the driver look for
+ /dev/input/js# before /dev/js#.
+
+ Peter Wang renamed fixed point functions to be prefixed with "fix" instead
+ of "f", to avoid clashes with some libcs. Backwards compatibility is
+ provided using static inline functions.
+
+ Peter Wang fixed two problems with emergency exits under Linux/Unix.
+
+ Eric Botcazou changed the updating logic of the QNX Photon graphics
+ driver.
+
+ Eric Botcazou added a doc for the wfixicon utility, with the help of
+ Laurence Withers.
+
+ Angelo Mottola unicodified allegro_message on BeOS and wrote a new BeOS
+ keyboard driver (using the shared pckeys system).
+
+ Eric Botcazou fixed a problem with David Capello's d_menu_proc
+ steal/return mouse focus patch.
+
+ Peter Wang made passing NULL to install_allegro() as the atexit_ptr
+ parameter mean allegro_exit() won't be installed as an atexit()
+ callback, as suggested by Javier Gonzalez.
+
+ Lorenzo Petrone added a gfxinfo utility.
+
+ Eric Botcazou added fetch_mode_list() to the QNX Photon Direct driver.
+
+ Peter Wang made X desktop_color_depth() able to return 15 bpp.
+
+ Grzegorz Adam Hankiewicz updated Spanish translation strings.
+
+ Peter Wang fixed a problem with X shutdown sequence.
+
+ Eric Botcazou repaired the QNX build process, revamped the layout of the
+ QNX port sources and made some fixes.
+
+ Peter Wang disabled the SVGAlib mode fetching code as it was causing
+ problems with other drivers.
+
+ Angelo Mottola added BeOS notes to the ABI compatibility doc.
+
+ Eric Botcazou fixed a bug in the Windows locking code that caused the
+ grabber to crash on switch out.
+
+ Eric Botcazou fixed a bug in the handling of recursive sub-bitmaps under
+ Windows.
+
+ Eric Botcazou fixed a bug preventing old style password-protected
+ packfiles from loading in the grabber.
+
+ Lorenzo Petrone added two FAQ entries on DGA2 problems.
+
+ Grzegorz Adam Hankiewicz revamped the structure of the docs directory.
+
+ Stepan Roh updated the Czech translation.
+
+ Javier Gonzalez fixed a bug in the DirectSound driver related to the loop
+ playing modes.
+
+ David Capello fixed a problem with submenus which overlapped their
+ parents, where focus would pop back to the parent instead of the child.
+
+ 3.9.40: Eric Botcazou enabled SSE support under Linux. Also reduced the
+ delay in the DOS Sidewinder init code. Made the definition of _AL_DLL
+ for MinGW32 consistent with other Windows ports.
+
+ 3.9.40: Henrik Stokseth improved make install to install only the needed
+ headers from the include/allegro/platform directory.
+
+ 3.9.40: Vincent Penquerc'h updated 7 makefiles after his header splitting
+ patch.
+
+ 3.9.40: Robert J. Ohannessian added two new entries to the GFX_VTABLE
+ structure.
+
+ 3.9.40: Eric Botcazou replaced sprintf() by snprintf() in the Linux/Unix
+ code. Increased the delay in the Windows switch handling code.
+ Unicodified the GFX mode selector and fixed some glitches. Added a new
+ test dubbed filetest. Fixed more unicode string problems. Unified the
+ handling of system directory variables in the Windows makefiles. Made
+ two strings translatable in the GFX mode selector.
+
+ 3.9.40: Ben Davis added support for timers with parameters under Windows.
+
+ 3.9.40: Eric Botcazou fixed the bug in the asm sprite functions when
+ used with sub-bitmaps. Fixed a problem of the new header layout for
+ platforms not supporting asm.
+
+ 3.9.40: George Foot and Eric Botcazou fixed the C fceil() function and
+ added the ffloor() function.
+
+ 3.9.40: Chris Graham suggested to add a new flag for Windows NTFS
+ compressed files.
+
+ 3.9.40: Henrik Schmidt and Eric Botcazou found a workaround for the
+ switching problem under Windows.
+
+ 3.9.40: Eric Botcazou revamped the Borland C++ build process. Now it
+ targets BC++ 5.5. Made pack_fdopen() an exported internal function.
+ Reverted to the 3.9.38 code for 16-bit audio streaming with DirectSound.
+
+ 3.9.40: Vincent Penquerc'h contributed a rather large split-up/
+ reorganization of the Allegro header files. Henrik and Eric did some
+ related clean-up and fixing.
+
+ 3.9.40: Peter Wang updated put_backslash() docs.
+
+ 3.9.40: Eric Botcazou modified the way DirectDraw surfaces are
+ enumerated. Fixed compilation errors/warnings with BC++. Made
+ generate_optimized_palette_ex() a static function. Worked around the
+ DOS limitations for al_findfirst() and for_each_file(). Moved
+ platform-dependent stuff out of src/fsel.c.
+
+ 3.9.40: Peter Wang updated timer docs for non-DOS. Added ABI
+ compatibility readme.
+
+ 3.9.40: Javier Gonzalez removed all references to the RSXNT build.
+
+ 3.9.40: Vincent Penquerc'h made it so that users can provide their own
+ ustrdup().
+
+ 3.9.40: Robin Burrows fixed two glitches in the DirectDraw code.
+
+ 3.9.40: Peter Wang fixed a problem where XUnlockDisplay was called after
+ XCloseDisplay.
+
+ 3.9.40: Eric Botcazou removed old Sidewinder asm driver. Cleaned up
+ buffer usage in DIGMID. Fixed unicode support in the DIGMID driver.
+ Replaced all occurrences of SEND_MESSAGE() by object_message().
+
+ 3.9.40: Annie Testes caught a misordering in the X system shutdown.
+
+ 3.9.40: Eric Botcazou increased the size of filename buffers to 1024
+ bytes.
+
+ 3.9.40: Sven Sandberg improved fix.bat script.
+
+ 3.9.40: David Capello fixed a problem with lost GUI mouse clicks.
+
+ 3.9.40: Vincent Penquerc'h removed two hard-coded list sizes in grabber.
+
+ 3.9.40: Peter Wang added a little clarification regarding
+ mouse_accel_factor.
+
+ 3.9.40: Eric Botcazou made debugging functions revert to ASCII strings.
+ Added some defines for backwards compatibility with former cpu_* flags.
+ Fixed a compilation problem under DJGPP.
+
+ 3.9.40: Henrik Stokseth added VBE/AF fetch_mode_list().
+
+ 3.9.40: Robert J. Ohannessian revamped the retrieval mechanism of CPU
+ capabilities and added some new flags.
+
+ 3.9.40: Eric Botcazou fixed various mouse cursor problems under Windows.
+ Updated docs about the DIGI_DIRECTX drivers.
+
+ 3.9.40: Javier Gonzalez fixed audio streams in Windows.
+
+ 3.9.40: Peter Wang improved the XDGA2 driver by removing unneccessary
+ scrolling, which also resulted in speed-ups due to less
+ locking/unlocking. The original fix was by Michael Bukin.
+
+ 3.9.40: Eric Botcazou and Javier Gonzalez added some documentation on
+ static linking with MSVC/MinGW32.
+
+ 3.9.40: Peter Wang fixed sonames for debug and profile libs. Also added
+ a 'configure' check that ld supports -export-modules before enabling
+ modules.
+
+ 3.9.40: Annie Testes found ASCII strings that needed to be converted.
+ Also added a pack_fdopen() function.
+
+ 3.9.40: Robert J. Ohannessian clarified some Dev-C++ instructions.
+ Fixed fix.bat script under MinGW32/Win2k.
+
+ 3.9.40: Marcel Smit corrected a bug that caused errors when drawing
+ perspective-correct polygons facing the screen. (dz=0)
+
+ 3.9.40: Peter Wang made install_timer_int static. Also moved
+ allegro_404_char into public API.
+
+ 3.9.40: Laurence Withers added docs for allegro_404_char.
+
+ 3.9.40: Eric Botcazou fixed a little glitch with menu auto-opening. Also
+ fixed a color glitch in the Windows windowed driver on 8-bit desktops.
+
+ 3.9.40: Salvador Eduardos Tropea fixed inline friend declarations with
+ bodies. (gcc 3.0.x problem)
+
+ 3.9.40: Peter Wang improved behaviour between mouse auto-opening menus
+ and navigating with keyboard. Also unspartanised the ustrtok_r() docs.
+
+ 3.9.40: Henrik Stokseth replaced the mmxtest with a more advanced
+ assembler capabilities testing.
+
+ 3.9.40: Eric Botcazou re-enabled full pairing on Pentium for five color
+ conversion routines. Applied xor vs. mov instruction-length optimization
+ to the non-MMX code. Applied %ecx vs. %edx instruction-length
+ optimization to the non-MMX code. Updated the mouse_accel_factor docs.
+
+ 3.9.40: Peter Wang eliminated use of static buffers by uconvert() in
+ several places.
+
+ 3.9.40: David A. Capello made d_menu_proc steal/return focus when
+ activated/deactivated.
+
+ 3.9.40: Henrik Stokseth added Out of Environment space detection on the
+ fix.bat script.
+
+ 3.9.40: Eric Botcazou fixed a non ANSI C compliant behaviour in
+ usprintf().
+
+ 3.9.40: Seunghwan Ji made makedoc output correct html and rtf files for
+ Korean.
+
+ 3.9.39: Robert J. Ohannessian added -? and --help options to dat.
+
+ 3.9.39: Sven Sandberg and Grzegorz Adam Hankiewicz fixed some errors in
+ the documentation.
+
+ 3.9.39: Annie Testes fixed several glitches related to unicode support.
+
+ 3.9.39: Henrik Stokseth added an internal _al_sane_realloc() function
+ with guaranteed behaviour. Used this to fix a memory leak and updated
+ the FAQ.
+
+ 3.9.39: Eric Botcazou and Peter Wang updated the documentation on:
+ file attribute flags, request_scroll and request_video_bitmap.
+
+ 3.9.39: Eric Botcazou unified the use of internal timers in Windows
+ drivers. Also let digitest use max volume of Allegro mixer.
+
+ 3.9.39: Paul Hampson improved again the DOS SNESpad joystick driver.
+
+ 3.9.39: Eric Botcazou revamped the locking mechanism of the DGA2 driver.
+ Also fixed some memory leaks.
+
+ 3.9.39: Peter Wang added mode fetching for X11 fullscreen and DGA
+ fullscreen drivers.
+
+ 3.9.39: Robert J. Ohannessian fixed 16bit masked blit SSE code and
+ removed unused instruction in the other blitters.
+
+ 3.9.39: Salvador Eduardos Tropea added some GCC 3.x fixes.
+
+ 3.9.39: Peter Wang added a check if a module listed in modules.lst exist
+ before trying to load it.
+
+ 3.9.39: Charles Wardlaw made alert/alert3 use transparent background for
+ text label.
+
+ 3.9.39: Eric Botcazou added a flush_config_file() API function. Also added
+ a hfill() method to the GFX_VTABLE structure.
+
+ 3.9.39: Peter Wang fixed some memory leaks.
+
+ 3.9.39: Eric Botcazou fixed two compilation warnings with gcc > 2.95.
+
+ 3.9.39: Johan Peitz contributed 'Alex the Allegator' icon.
+
+ 3.9.39: Angelo Mottola fixed safe fullscreen bug and fetch_mode_list()
+ for BeOS.
+
+ 3.9.39: Peter Wang updated XDGA2 and SVGAlib driver's fetch_mode_list()
+ function.
+
+ 3.9.39: Henrik Stokseth rewrote the mode-list API, updated the code and
+ updated the documentation.
+
+ 3.9.39: Grzegorz Adam Hankiewicz updated all URLs in the Allegro sources
+ and documentation.
+
+ 3.9.39: Eric Botcazou fixed cmplog script for perl 5.6.1.
+
+ 3.9.39: Peter Wang added a FAQ entry.
+
+ 3.9.39: Peter Wang fixed up the sound subsystem which he accidentally
+ broke when he introduced the dynamic modules.
+
+ 3.9.39: Eric Botcazou fixed a compilation warning. Also added support
+ for 8-bit desktops to the windows windowed driver. Fixed color shifts in
+ the color convertors from 8-bit. Fixed a bug in the 8->8 color conversion
+ routine.
+
+ 3.9.39: Javier Gonzalez contributed bidirectional looping support for the
+ directsound driver.
+
+ 3.9.39: Robert J. Ohannessian and Henrik Stokseth did a large update on
+ the installation instructions for Mingw32.
+
+ 3.9.39: Eric Botcazou cleaned up windows dll version info sheet and let
+ the windows makefiles use implicit rules on some file targets. Fixed a
+ compilation glitch with MSVC.
+
+ 3.9.39: Henrik Stokseth added support for building RPMs with SuSE Linux.
+
+ 3.9.39: Peter Wang fixed some off-by-one errors. Fixed unix makefile.
+ Fixed disabling of dynamic modules.
+
+ 3.9.39: Eric Botcazou and Grzegorz Adam Hankiewicz finished translation
+ of the allegro.spec file.
+
+ 3.9.39: Eric Botcazou re-added a faq entry on DirectX version problem.
+
+ 3.9.39: Grzegorz made fbcon a module.
+
+ 3.9.39: Peter Wang removed allegro-enduser.spec as it is no longer needed.
+ Also contributed a rewrite of the allegro.spec file, and updated the
+ scripts to make the rpm. The new allegro.spec file was based on one
+ contributed by Osvaldo Santana Neto. Peter also allowed configure to give
+ linker flags to allegro-config (for modules). Also let _unix_find_resource
+ search in /usr/[local/]share/allegro for .dat files.
+
+ 3.9.39: Javier Gonzalez contributed backward playing support for the
+ directsound driver.
+
+ 3.9.39: Eric Botcazou fixed a glitch with backward playing in the digitest
+ test.
+
+ 3.9.39: Salvador Eduardos Tropea made a small update on the cygwin section
+ of readme.mgw.
+
+ 3.9.39: Peter Wang fixed a problem with BSD make and Mac directory
+ separators ':'. Documented gfx_cardw variable.
+
+ 3.9.39: Sven Sandberg fixed a nasty side-effect of clear() inlining on
+ Watcom.
+
+ 3.9.39: Laurence Withers fixed a crash bug in the mode-selector.
+
+ 3.9.39: Peter Wang removed SIGIO asynch stuff since it's not needed when
+ we have pthreads. Updated documentation to mention dynamic modules.
+ Added configure option to disable threads.
+
+ 3.9.39: Burton Radons fixed a bug in his dissolve blender.
+
+ 3.9.39: Eric Botcazou fixed a bug in the menus caused by auto-opening.
+
+ 3.9.39: Henrik Stokseth updated the makefiles to use -mcpu=pentium instead
+ of the depreciated -mpentium gcc option. Also let the packaging scripts
+ run autoconf and remove hidden or leftover files.
+
+ 3.9.39: Eric Botcazou cleaned up the windows sound code. Also clarified
+ the code in the core menu function. Corrected a unicode glitch.
+ Removed remaining references to ALLEGRO_NO_FINDFIRST. Added a unified
+ al_find*() interface. Made the Portuguese translation file of the former
+ Portuguese (Br) file. Fixed a few keyboard configuration files. Changed
+ pl.cfg EOLN delimiter to \r\n.
+
+ 3.9.39: Grzegorz Godlewski contributed a Polish localization patch.
+ Also added support for lower and upper altgr tables.
+
+ 3.9.39: Eric Botcazou fixed a bug in the keyconf utility caused by the
+ sectionification.
+
+ 3.9.38: Robert J. Ohannessian added the following to the color convertor:
+ color copy routines needed by the BeOS port, support for cross-conversion
+ between 15-bit and 16-bit colors, support for conversion to 8-bit color,
+ support for rectangles of any width and added two new MMX routines.
+
+ 3.9.38: Henrik Stokseth rewrote get_gfx_mode_list() likewise rewrote the
+ mode-selector to use get_gfx_mode_list(). Also added fetch_mode_list()
+ functions on the DirectX, VGA, Mode-X and Xtended GFX drivers.
+
+ 3.9.38: Angelo Mottola fixed problems with SMP on the BeOS port.
+
+ 3.9.38: Eric Botcazou fixed some problems with the non-MMX code in the
+ color convertor.
+
+ 3.9.38: Sven Sandberg improved spline() for DRAW_MODE_TRANS
+
+ 3.9.38: Peter Wang renamed clear() to clear_bitmap(). clear() is still
+ provided for backwards compatibility.
+
+ 3.9.38: Stepan Roh made fractal generator work under non-Intel
+ processors.
+
+ 3.9.38: Eric Botcazou made a valid display switch mode of SWITCH_NONE
+ under DOS.
+
+ 3.9.38: Angelo Mottola made the BeOS port use the new unified color
+ conversion routines.
+
+ 3.9.38: Peter Wang added check to see if display is local under X11.
+
+ 3.9.38: Eric Botcazou and Sven Sandberg fixed compilation under
+ Watcom 10.6.
+
+ 3.9.38: Elias Pschernig contributed an icon resource fixer for the
+ Windows port and added support for shared library under BeOS.
+
+ 3.9.38: Angelo Mottola added a bfixicon utility.
+
+ 3.9.38: Stepan Roh made the native Allegro time format of ANSI time_t.
+
+ 3.9.38: Peter Wang added an ustrtok_r() function.
+
+ 3.9.38: Robert J. Ohannessian optimized some masked_blits with SSE
+ instructions.
+
+ 3.9.38: Angelo Mottola did a sound fix for audiostream output and SMP
+ machines and added triple buffering support on the BeOS port.
+
+ 3.9.38: Angelo Mottola added fetch_mode_list() support to the BeOS
+ fullscreen driver.
+
+ 3.9.38: Eric Botcazou changed the acceleration scheme for the mouse under
+ Windows.
+
+ 3.9.38: Peter Wang added fetch_mode_list() support to the svgalib driver.
+
+ 3.9.38: Peter Wang added pthread timer and removed dependancy to SIGALRM.
+
+ 3.9.38: Henrik Stokseth added Windows XP detection.
+
+ 3.9.38: Andreas Kluge fixed a bug with volume setting in the DOS
+ Soundscape driver.
+
+ 3.9.38: Angelo Mottola rewrote the BeOS sound driver to use the
+ BSoundPlayer class.
+
+ 3.9.38: Robert J. Ohannessian added SSE and SSE2 detection.
+
+ 3.9.38: Connelly Barnes fixed a bug with the DirectSound pan.
+
+ 3.9.38: Eric Botcazou added support of switch modes to the test program.
+
+ 3.9.38: Eric Botcazou modified the Windows switch mechanism.
+
+ 3.9.38: Angelo Mottola added fullscreen display switching support and did
+ many fixes and cleanups on the BeOS port.
+
+ 3.9.38: Henrik Stokseth added code to get more os info under unix.
+
+ 3.9.38: Nimrod Abing fixed a bug in the config routines related to the
+ NULL section.
+
+ 3.9.38: Eric Botcazou fixed a crash in the Windows windowed driver on fast
+ machines.
+
+ 3.9.38: Ronaldo Hideki Yamada did a large update on the PowerMac port and
+ added a midi driver.
+
+ 3.9.38: Henrik Stokseth generalised the support for processor specific
+ optimisations in some makefiles.
+
+ 3.9.38: Evert Glebbeek put set_gfx_mode on a diet and added config entry
+ for specifying the card to use for GFX_AUTODETECT_WINDOWED.
+
+ 3.9.38: Robert J. Ohannessian made blit not convert between colordepths
+ for video bitmaps. (for AllegroGL)
+
+ 3.9.38: Peter Wang made fix_filename_slashes() handle both types of
+ slashes.
+
+ 3.9.38: Grzegorz Adam Hankiewicz implemented a switch in makedoc to check
+ for long (>77) doc lines.
+
+ 3.9.38: Owen Rudge contributed a DLL version resource script.
+
+ 3.9.38: Sven Sandberg made the rotation functions faster, more accurate
+ and working with any type of bitmap. Also removed
+ rotate_scaled_sprite_flip().
+
+ 3.9.38: Angelo Mottola added fetch_mode_list() support to DGA2.
+
+ 3.9.38: David A. Capello made test program use transparent polygon types.
+
+ 3.9.38: Owen Rudge contributed a mkdata.bat script.
+
+ 3.9.38: Grzegorz Adam Hankiewicz added reload_config_texts().
+
+ 3.9.38: Eric Botcazou added an enhanced building mechanism for DLL
+ export definition files.
+
+ 3.9.38: Eric Botcazou added a new unicode example program and did a ton of
+ small fixes.
+
+ 3.9.37: Johan Peitz fixed and enhanced the Win32 joystick driver.
+
+ 3.9.37: Sven Sandberg added Ctrl + arrow keys to d_edit_proc().
+
+ 3.9.37: Eric Botcazou changed the color key for the Windows overlay
+ driver to bright pink.
+
+ 3.9.37: Eric Botcazou reverted some changes he made to the timer core
+ last release which were causing problems with the MIDI player, and
+ removed the Windows multithreaded timer driver.
+
+ 3.9.37: Henrik Stokseth made some updates to the OS detection code, and
+ added a os_multitasking variable.
+
+ 3.9.37: Eric Botcazou fixed a problem in the config routines, where
+ entries in the NULL section were hiding duplicate entries in other
+ sections.
+
+ 3.9.37: Eric Botcazou made the setup program use Unicode functions.
+
+ 3.9.37: Henrik Stokseth unified the fix* scripts, and gave them new
+ options.
+
+ 3.9.37: Peter Wang added support for dynamically loaded modules under
+ Unix. The SVGAlib, ALSA digital, ALSA MIDI, ESD and DGA2 drivers will
+ be built as modules when possible. This removes external dependencies
+ on the main library and improves binary transportability under Linux.
+
+ 3.9.37: Eric Botcazou made many changes and bug fixes to the Unicode
+ string functions, and their use in the library. The old functions now
+ behave exactly like the libc equivalents, while the new functions (the
+ 'z' functions) behave more sanely. This change affects most code which
+ uses the Unicode functions.
+
+ 3.9.37: Bertrand Coconnier changed the recently merged scene rendering
+ API, fixed a bug, and provided a new example program. The API change
+ will affect all code which uses the scene functions.
+
+ 3.9.37: Laurence Withers wrapped registration of the bitmap file types
+ in a constructor. Where constructors are supported, this should reduce
+ the executable size when statically linking (unless you use the bitmap
+ loaders, of course).
+
+ 3.9.37: Ben Davis modified the set_volume_per_voice scale. Please see
+ the docs for this function if you have used it in the past.
+
+ 3.9.37: Eric Botcazou worked around a DOS mouse bug under Win2k.
+
+ 3.9.37: Eric Botcazou added VGA Mode 13h support under DirectX 5 or
+ greater.
+
+ 3.9.37: Henrik Stokseth added a get_gfx_mode_list() function, and the
+ implementation of it for the VESA driver.
+
+ 3.9.37: Eric Botcazou and Annie Testes toiled hard to avoid buffer
+ overflows (particularly with regards to the Unicode functions).
+
+ 3.9.37: Eric Botcazou fixed a mouse mickeys bug and cleaned up the
+ input subsystem under Windows.
+
+ 3.9.37: Eric Botcazou made two minor changes in the handling of index 0
+ in paletted modes.
+
+ 3.9.37: Eric Botcazou added a transparency preserving feature to the
+ grabber and dat utility.
+
+ 3.9.37: Eric Botcazou fixed a crash when alt-tabbing in page flipping
+ under Windows.
+
+ 3.9.37: Peter Wang added gui_menu_draw_menu and gui_menu_draw_menu_item
+ to allow customising the look of the GUI menus (to a certain extent).
+
+ 3.9.37: Angelo Mottola added support for the new
+ GFX_AUTODETECT_FULLSCREEN and GFX_AUTODETECT_WINDOWED constants, which
+ we _all_ wholeheartedly agreed upon :-)
+
+ 3.9.37: Eduard Bloch made config vars which exist but are empty return
+ defaults.
+
+ 3.9.37: Elias Pschernig added a COLORCONV_KEEP_TRANS mode.
+
+ 3.9.37: Henrik Stokseth added support for compiling with Cygwin. It
+ works in Mingw compatibility mode.
+
+ 3.9.37: Angelo Mottola made GUI submenus automatically open when the
+ mouse hovers for long enough. (This was an old patch that finally got
+ merged.) Eric made some related modifications to it later.
+
+ 3.9.37: Eric Botcazou made clear_keybuf() not clear the key[] array.
+
+ 3.9.37: Sven Sandberg added a --quick option to fix scripts.
+
+ 3.9.37: Angelo Mottola did _loads_ of work on the QNX port (much too
+ much to document here).
+
+ 3.9.37: Eric Botcazou made the Win32 asm color conversion code for
+ windowed drivers available for other ports, and added a few other
+ converters. Isaac Cruz added one too.
+
+ 3.9.37: Eric Botcazou restructured the config file format. Some
+ previously unsectioned variables are now in sections.
+
+ 3.9.37: George Foot added a threading system to handle asynchronous
+ events, instead of using SIGALRM (under Unix).
+
+ 3.9.37: George Foot fixed some problems with pack_fgets().
+
+ 3.9.36: Eric Botcazou made it so that set_keyboard_rate(0, 0) will
+ disable keyboard repeat, as in the documentation.
+
+ 3.9.36: Eric Botcazou made some minor changes related to AllegroGL in
+ the window management code, and fixed two little mouse bugs Javier
+ Gonzalez had found (both under Windows).
+
+ 3.9.36: Eric Botcazou added a get_desktop_resolution() function for
+ Windows and X. Joshua Haberman added a BeOS version.
+
+ 3.9.36: Angelo Mottola comprehensively started a QNX port.
+
+ 3.9.36: Robert Ohannessian corrected src/dest ordering in additive
+ blenders.
+
+ 3.9.36: Eric Botcazou improved support of external windows in Windows.
+
+ 3.9.36: Peter Wang updated the SVGAlib driver for version 2.
+
+ 3.9.36: Peter Wang added a fullscreen version of the X-Windows graphics
+ driver. The original was by Benjamin Joel Stover.
+
+ 3.9.36: Peter Wang made grabber use file_select_ex(). This is just here
+ so you don't get a shock :-)
+
+ 3.9.36: Eric Botcazou fixed some small bugs in the DirectSound input code.
+
+ 3.9.36: Eric Botcazou fixed the NumLock state in X not matching
+ keyboard LEDs.
+
+ 3.9.36: Eric Botcazou reenabled the multi-threaded timer under Windows.
+
+ 3.9.36: Eric Botcazou and Javier Gonzalez made the keyboard repeat
+ system more efficient.
+
+ 3.9.36: Eric Botcazou fixed some asm blitters, and also a bug with
+ changing timer speeds.
+
+ 3.9.36: Peter Wang made the keypad return / * - + ASCII values even if
+ NumLock is off, under Linux console.
+
+ 3.9.36: Ronaldo Hideki Yamada made a big update of the Mac port,
+ including some new PPC files.
+
+ 3.9.36: The GGI driver was removed, due to its inability to actually
+ work. It is no longer supported, unless someone rewrites it.
+
+ 3.9.36: Eric Botcazou fixed a problem with the GDI driver when compiled
+ with MSVC.
+
+ 3.9.36: Some MIDI fixes by Javier Gonzalez and Eric Botcazou.
+
+ 3.9.36: Grzegorz Adam Hankiewicz improved the fb.modes line parsing
+ function in the fbcon driver.
+
+ 3.9.36: Grzegorz Adam Hankiewicz changed the behaviour of GFX_SAFE.
+ This means that "set_gfx_mode(GFX_SAFE, ...)" now returns an error if
+ it is unable to set a video mode, just like any other video driver.
+
+ 3.9.36: Eric Botcazou fixed volume setting in Windows.
+
+ 3.9.36: Eric Botcazou added DirectX 3 compatibility.
+
+ 3.9.36: Nick Kochakian added input routines to the DirectSound driver.
+ It was also modified by Javier Gonzalez.
+
+ 3.9.35: Eric Botcazou made Windows restore the original sound volume
+ after an Allegro program quits.
+
+ 3.9.35: Eric Botcazou fixed sample looping in DirectSound driver.
+
+ 3.9.35: Grzegorz Adam Hankiewicz solved some color problems in the
+ demo game.
+
+ 3.9.35: Angelo Mottola implemented a close button hook for X11.
+
+ 3.9.35: Eric Botcazou fixed _the_ Windows 2000 keyboard bug.
+
+ 3.9.35: Eric Botcazou made some changes to the locking/unlocking
+ mechanism in the Windows port.
+
+ 3.9.35: Laurence Withers made some modules avoid linking
+ dependencies.
+
+ 3.9.35: Javier Gonzalez added close button support for Windows.
+
+ 3.9.35: Eric Botcazou improved mouse handling in the GFX_GDI driver
+ and fixed some other mouse glitches.
+
+ 3.9.35: Peter Wang made set_mouse_sprite(NULL) regenerate the
+ default arrow bitmap (using the current palette).
+
+ 3.9.35: Eric Botcazou made hardware accelerated primitives stop
+ when the user switches out in Windows.
+
+ 3.9.35: Tom St Denis fixed clipping of transparent objects.
+
+ 3.9.35: Eric Botcazou and Javier Gonzalez improved switching in
+ Windows and other things.
+
+ 3.9.35: Peter Wang made the Linux joystick driver use standard
+ constants.
+
+ 3.9.35: Sven Sandberg changed the Z-buffer API.
+
+ 3.9.35: Peter Wang made the default mouse sprite independent of the
+ palette in 8 bpp modes.
+
+ 3.9.35: Bertrand Coconnier added documentation for the P3D merge.
+
+ 3.9.35: Angelo Mottola fixed desktop_color_depth() and added window
+ close button support for the BeOS port.
+
+ 3.9.35: Ben Davis added the set_window_close_button() and
+ set_window_close_hook() framework.
+
+ 3.9.35: Peter Wang exposed the mouse_sprite, mouse_x_focus and
+ mouse_y_focus variables.
+
+ 3.9.35: Robert Ohannessian and Javier Gonzalez fixed bad clearing
+ of subbitmaps.
+
+ 3.9.35: Peter Wang renamed GFX_XDFS to GFX_XDGA_FULLSCREEN.
+
+ 3.9.35: Henrik Stokseth updated the cross-compilation system.
+
+ 3.9.35: Tomohiko Sugiura added some keys and renamed some JP keys.
+
+ 3.9.35: Eric Botcazou added a DirectDraw2 interface, with support
+ for refresh rates.
+
+ 3.9.35: Javier Gonzalez made allegro_message() use the title from
+ set_window_title() in Windows.
+
+ 3.9.35: Andreas Kluge fixed division bugs in the fix class.
+
+ 3.9.35: Stepan Roh documented the FA_* flags.
+
+ 3.9.35: Peter Wang added hooks to allow overriding the look of
+ standard dialogs.
+
+ 3.9.35: Peter Wang changed X window placement and mapping behaviour.
+
+ 3.9.35: David A. Capello made dotted_rect() avoid bank switches.
+
+ 3.9.35: Eric Botcazou fixed a freezing problem under Window with
+ locking/unlocking bitmaps under heavy load. He received help
+ tracking down the bug from Javier Gonzalez.
+
+ 3.9.35: Stepan Roh fixed a bug with FA_RDONLY constant under Unix.
+
+ 3.9.35: Eric Botcazou cleaned up the Windows graphics subsystem.
+
+ 3.9.35: "Sask Allegro" added support for more than two joysticks in
+ the Windows port.
+
+ 3.9.34: Ben Davis made close button in Windows windowed modes not
+ simulate Escape key, in preparation for new behaviour (in next WIP).
+
+ 3.9.34: Laurence Withers fixed a problem with accents in keyconf.
+
+ 3.9.34: Javier Gonzalez added DIGMID to the Windows MIDI drivers list.
+
+ 3.9.34: Eric Botcazou cleaned up the DirectDraw subsystem.
+
+ 3.9.34: Eric Botcazou made the DirectDraw overlay driver comply with
+ page flipping and triple buffering code, amongst other things.
+
+ 3.9.34: Javier Gonzalez corrected mouse movement speed in Windows.
+
+ 3.9.34: Ben Davis adapted polygon functions to handle two coincident
+ vertices, and changed and clarified texture coordinate alignment in
+ code and documentation.
+
+ 3.9.34: Grzegorz Adam Hankiewicz fleshed out the docs for Unicode
+ functions, adapting from djgpp and gcc docs.
+
+ 3.9.34: Eric Botcazou fixed a triple buffering problem in the
+ DirectDraw accelerated driver.
+
+ 3.9.34: Henrik Stokseth added support for cross-compilation in the
+ mingw32 build.
+
+ 3.9.34: Grzegorz Adam Hankiewicz updated more examples for GFX_SAFE.
+
+ 3.9.34: Ben Davis added set_volume_per_voice(), made silent voices
+ continue playing and fixed other minor bugs.
+
+ 3.9.34: Ben Davis fixed a bug in create_rgb_table().
+
+ 3.9.34: Angelo Mottola added display switching routines for BeOS and
+ fixed some bugs.
+
+ 3.9.34: Laurence Withers updated documentation about `const'.
+
+ 3.9.34: Ronaldo Hideki Yamada contributed a macintosh port of Allegro.
+
+ 3.9.34: Grzegorz Adam Hankiewicz changed and documented new GFX_SAFE
+ behaviour (that color depth is undefined), updated the fbcon driver to
+ take advantage of this and updated example programs.
+
+ 3.9.34: Peter Pavlovic fixed a bug caused by file selector stretching.
+
+ 3.9.34: Bertrand Coconnier fixed bugs related to poly3d(); removed
+ never-called C versions of scanline functions for POLYTYPE_FLAT and
+ non-8bpp POLYTYPE_GCOL; and made clip3d() and clip3d_f() functions
+ compliant with Z-buffered polygons.
+
+ 3.9.34: Stepan Roh added C version of masked_stretch_blit().
+
+ 3.9.34: Angelo Mottola did more work on BeOS: hardware acceleration
+ (rect, hline, vline, clear_to_color, blit); mouse fix in windowed mode;
+ desktop_color_depth(); yield_timeslice();
+
+ 3.9.34: Peter Wang retroactively updated CHANGES and AUTHORS from
+ late 3.9.33 to present using CVS logs and email archives, and
+ possibly messed up.
+
+ 3.9.34: Angelo Mottola added a BeOS windowed driver (originally by
+ Peter Wang), a BeOS MIDI driver, mouse wheel support under BeOS and
+ made many bug fixes and changes to other BeOS code and documentation.
+
+ 3.9.34: Laurence Withers fixed dat2s output of fonts for new font
+ subsystem.
+
+ 3.9.34: Peter Wang made the SVGAlib driver more robust.
+
+ 3.9.34: Peter Wang changed the way Intellimouse protocols are selected
+ under Linux console.
+
+ 3.9.34: Eric Botcazou added file_select_ex and reverted file_select to
+ old behaviour.
+
+ 3.9.34: Laurence Withers designed and implemented a new FONT structure,
+ which should provide many advantages over the old one.
+
+ 3.9.34: Eric Botcazou made more fixes to Windows code.
+
+ 3.9.34: Bertrand Coconnier added a z-buffer rendering mode for 3D
+ polygons (derived from Calin Andrian's P3D library) and an example
+ program for it.
+
+ 3.9.34: Michael Bukin added customization for keycode to scancode
+ mapping in X.
+
+ 3.9.34: Peter Wang added mouse wheel support to d_textbox_proc and
+ d_slider_proc, and made file selector dialog stretch.
+
+ 3.9.34: Tom Fjellstrom added an ALSA MIDI driver.
+
+ 3.9.34: Eric Botcazou made some changes to the Windows windowed driver.
+
+ 3.9.34: Grzegorz Adam Hankiewicz updated the documentation and the
+ makedoc program to produce better .texi output. The new version works
+ very well with the texi2dvi program, which produces fine ready to print
+ device independent output. Also documented the new unix makefile targets.
+
+ 3.9.34: George Foot added --env option to allegro-config script.
+
+ 3.9.34: Benjamin Stover made some vararg fixes in unicode.c and added a
+ workaround for missing defines in fbcon.c.
+
+ 3.9.34: Robin Burrows added a Windows waveOut sound driver.
+
+ 3.9.34: Eric Botcazou changed desktop_color_depth() for Windows.
+
+ 3.9.34: Angelo Mottola added line switching and refresh rate support to
+ DGA2 driver.
+
+ 3.9.34: Bertrand Coconnier added scanline subdivisions and fixed 3D
+ polygon drawing.
+
+ 3.9.34: Michael Bukin modified text_mode to return previous mode.
+
+ 3.9.34: Peter Pavlovic fixed scrollbar display in grabber and improved
+ scrolling in GUI objects.
+
+ 3.9.34: anarko made GUI objects restore textmode.
+
+ 3.9.34: Laurence Withers added font destroy hook.
+
+ 3.9.34: Vincent Penquerc'h modified the mouse button press/release events
+ so they have higher priority than double-click events.
+
+ 3.9.34: Eric Botcazou improved colormap handling in XDGA.
+
+ 3.9.34: Robin Burrows provided a new page flipping code for the DirectDraw
+ subsytem, which now works on every graphic card.
+
+ 3.9.33: Henrik Stokseth updated the mingw32 makefile, the documentation
+ and sent in some other related fixes and updates. You will never again
+ need MSVC to compile the Allegro DLLs. ;o)
+
+ 3.9.33: Peter Puck contributed some updates to Allegro's win32 code
+ which got the native mingw32 build fully working.
+
+ 3.9.33: Michael Bukin changed the auto-repeat handling in X,
+ sched_yield handling for Unix, fixed _add_exit_func, and added list of
+ active dialogs to the GUI.
+
+ 3.9.33: Vincent Penquerc'h sped up the C versions of the RLE sprite
+ drawing routines by quite a bit.
+
+ 3.9.33: Peter Wang improved TGA palette loading.
+
+ 3.9.33: Laurence Withers made more functions const-correct.
+
+ 3.9.33: Isaac Cruz moved Windows bitmap locking to a separate .S file,
+ changed the update logic for the windowed driver, and added an accelerated
+ vline implementation.
+
+ 3.9.33: Stephen Kittelson fixed a bug in pckeys.c, and changed the ASCII
+ values returned for a few weird key combinations.
+
+ 3.9.33: Peter Wang made various functions const-correct.
+
+ 3.9.33: Peter Pavlovic made aesthetic modifications to the GUI menu
+ system.
+
+ 3.9.33: Javier Gonzalez suggested that the file and mode selector dialogs
+ should use popup_dialog.
+
+ 3.9.33: Vincent Penquerc'h added the install-gzipped-man makefile target,
+ patched some of the EINTR handling, and made the OSS driver detect whether
+ the device is 16 bit or not.
+
+ 3.9.33: Peter Pavlovic modified the Slovak keyboard mapping and made the
+ file selector detect available drives in Windows.
+
+ 3.9.33: Peter Wang added a sound (output only) driver for BeOS.
+
+ 3.9.33: Sven Sandberg fixed a typo in the definition of ustrdup, added
+ the uwidth_max function, provided the d_yield_proc function, and made
+ various dialogs use it.
+
+ 3.9.33: Michael Bukin made the DGA driver clear video memory and centre
+ the screen, if it's not fullscreen.
+
+ 3.9.33: Eduard Bloch suggested better ways to find the executable in
+ Unix.
+
+ 3.9.33: Andrew Geers added flipped rotated sprites.
+
+ 3.9.33: George Foot made the Unix makefile work for non-root users.
+
+ 3.9.33: Grzegorz Adam Hankiewicz made language config files be forced
+ to lower case.
+
+ 3.9.33: Grzegorz Adam Hankiewicz added documentation for findfirst(),
+ findnext(), and findclose(), and corrected the documentation for
+ get_executable_name().
+
+ 3.9.33: Stepan Roh made patches to allow compilation on IRIX.
+
+ 3.9.33: John Harger made a change to improve the stability of AllegroGL
+ in Windows.
+
+ 3.9.33: Sven Sandberg fixed a bug in the plain C 16bpp stretched blitter.
+
+ 3.9.33: George Foot fixed a bug in the i386 8bpp masked blit routines,
+ reported by Damian Yerrick.
+
+ 3.9.33: Eduard Bloch fixed a freeze caused by the ESD detection code.
+
+ 3.9.33: Vincent Penquerc'h added mouse button press/release events to
+ the GUI system.
+
+ 3.9.33: Peter Wang solved a conflict with SVGAlib.
+
+ 3.9.33: Vincent Penquerc'h added the XCRP and YCRP properties to bitmap
+ objects in datafiles.
+
+ 3.9.33: Vincent Penquerc'h made the GUI system not send MSG_DRAW to
+ hidden objects.
+
+ 3.9.33: Chris La Mantia pointed out that his code for textprintf_right
+ had mutated somehow.
+
+ 3.9.33: Peter Wang added a workaround for a mouse motion reporting bug
+ in some X servers.
+
+ 3.9.33: Eric Botcazou altered the DGA code to work better in 32bpp modes.
+
+ 3.9.33: Daniel Nilsson tweaked exstars and exlights
+
+ 3.9.33: Isaac Cruz fixed a nasty bug with subbitmap locking, and added
+ desktop_color_depth and yield_timeslice support to the Windows version.
+
+ 3.9.33: Peter Cech made uisspace() recognise non-ASCII space characters.
+
+ 3.9.32: S.Sakamaki added a function for controlling the refresh rate when
+ using the DOS VESA 3.0 driver (this could also be supported by some other
+ drivers if anyone wants to implement that).
+
+ 3.9.32: S.Suzuki added DOS drivers for the IF-SEGA /PCI, /PCI2, and /ISA
+ joystick interface cards.
+
+ 3.9.32: Fabrizio Gennari added DOS drivers for multisystem joysticks with
+ 9-pin connectors (Atari, Commodore 64, MSX).
+
+ 3.9.32: Peter Pavlovic improved the support for accented character maps
+ in the keyboard driver.
+
+ 3.9.32: Sven Sandberg optimised the GUI listbox scrolling to skip redraws
+ if it can't keep up with the update speed.
+
+ 3.9.32: Olly Betts did some work to make cross-compiling the djgpp
+ version work on Linux.
+
+ 3.9.32: Isaac Cruz improved the windowed mode ddraw driver, adding
+ support for many different color depth conversions.
+
+ 3.9.32: Vincent Penquerc'h added an update selection function to the
+ grabber.
+
+ 3.9.32: many bugfixes from various people.
+
+ 3.9.32: zipup.sh now generates dependencies entirely using standard Unix
+ tools and gcc, so it can setup all the supported platforms without
+ needing those compilers to be available (ie. I can create Watcom, BeOS,
+ and Mingw32 dependencies all from my Linux machine). This does require a
+ bit of cooperation from the different targets, though: they have to set
+ up their "make depend" target to override the standard gcc defines, and
+ wrap any non-standard header includes with "#ifndef SCAN_DEPEND".
+
+ 3.9.32: fixed (I hope :-) bug with non-GMT timezones in the datafile
+ update code.
+
+ 3.9.32: rewrote the Unicode usprintf() to piggyback on libc when
+ converting floating point data (too hard to get this right ourselves :-)
+
+ 3.9.31: Henrik Stokseth did some work on a native Mingw32 build. This is
+ currently incomplete, and unlikely to work right now since there have
+ been other changes in the Windows code since the version he started from.
+ At the moment this version is statically linked, using makefile.mgs, and
+ makefile.mgw still exists for the MSVC-piggyback version. The ultimate
+ goal is to get this native version building as a DLL in addition to
+ statically linked, at which point we can merge both makefiles into
+ makefile.mgw and remove makefile.mgs. Oh yeah, and there are currently no
+ docs for the native version.
+
+ 3.9.31: Greg Hackmann contributed a Borland C++ Builder port. Like the
+ RSXNT and Mingw32 versions, this is a client for the MSVC DLL, and not
+ able to compile Allegro directly itself, but allows you to build Allegro
+ programs using the Borland compiler.
+
+ 3.9.31: Robert Ohannessian added MMX optimisation for the 8 and 16 bit
+ clear() functions, and Jose Antonio Luque optimised the 16 bit blit() and
+ masked_blit() routines.
+
+ 3.9.31: Vincent Penquerc'h added a yield_timeslice() function (currently
+ implemented in DOS and Unix).
+
+ 3.9.31: added a desktop_color_depth() function (currently only
+ implemented in X: a Windows version will follow).
+
+ 3.9.31: Isaac Cruz added support for windowed modes in color depths other
+ than the current Windows desktop, and hardware accelerated system bitmaps.
+
+ 3.9.31: Jose Antonio Luque improved the Windows joystick driver.
+
+ 3.9.31: James Hyman added support for dithering truecolor down to
+ paletted images.
+
+ 3.9.31: Chris La Mantia added textout_right(), textprintf_right(), and
+ textprintf_justify() functions.
+
+ 3.9.31: Sven Sandberg added a ustrrchr() function, and improved the
+ usprintf() handling of large floating point values.
+
+ 3.9.31: Peter Pavlovic added a Slovak keyboard mapping and message
+ translation.
+
+ 3.9.31: Manni Heumann fixed some problems with the German keyboard
+ mapping.
+
+ 3.9.31: Michael Bukin improved the X keyboard and mouse handling, and
+ fixed some problems with building on non-GNU Unix systems.
+
+ 3.9.31: many bugfixes and tweaks from various people (sorry, my typing
+ patience has run out so you don't get a full list :-)
+
+ 3.9.31: Peter Wang added input support to the Linux OSS sound driver.
+
+ 3.9.31: David Kuhling optimised the i386/gcc fsqrt() code, and added an
+ fhypot() routine.
+
+ 3.9.30: fixed the double XOR that was making datafile passwords so easy
+ to reverse. The new code can still read old-style encrypted files, but
+ data written by this version can't be accessed by older copies of Allegro.
+
+ 3.9.30: made load_datafile(), load_datafile_object(), and the
+ file.dat#object syntax work correctly in all possible combinations.
+
+ 3.9.30: Vincent Penquerc'h added a scare_mouse_area() function.
+
+ 3.9.30: changed the DirectX surface locking mechanism, to improve the
+ performance of hardware accelerated drawing.
+
+ 3.9.30: George Foot improved the Linux LED code, and made the internal X
+ driver state visible via xalleg.h.
+
+ 3.9.30: added EINTR retry handling to read/write calls. I hope I got this
+ right: if anyone who properly groks this stuff could check over file.c,
+ that would be cool.
+
+ 3.9.30: made the Windows mouse driver work correctly in windowed mode.
+
+ 3.9.30: fixed various problems with Windows foreground/background
+ switching (keys were getting stuck down, timers weren't being paused, and
+ not all the right switching modes were being reported to the caller).
+
+ 3.9.30: made the X keyboard handler release all keys when it loses the
+ input focus, to avoid stuck buttons when you alt+tab between windows.
+
+ 3.9.30: made the allegro-lib script arguments compatible with the
+ standard used by GTK, ESD, etc, and renamed it to allegro-config. This
+ changes the syntax for linking Allegro programs on Unix: see readme.uni
+ for details of the new method.
+
+ 3.9.30: George Foot improved the Unix shared library system.
+
+ 3.9.30: Joerg Rueppel added a find_datafile_object() function.
+
+ 3.9.30: Peter Wang improved the SVGAlib driver.
+
+ 3.9.30: Peter Wang improved the Linux joystick driver.
+
+ 3.9.29: made the Windows code agree with other platforms about how video
+ bitmaps are supposed to behave.
+
+ 3.9.29: fixed some problems with the Windows mouse wheel support.
+
+ 3.9.29: added set_write_alpha_blender(), set_add_blender() and
+ create_blender_table() functions, and made the 32 bit version of
+ draw_trans_sprite() able to use 8 bit source images in conjunction with
+ set_write_alpha_blender(). In addition to being generally useful, using
+ these routines makes the sources for my SpeedHack entry much smaller :-)
+
+ 3.9.29: added uninstall targets to the Linux makefile.
+
+ 3.9.29: made the X windowed mouse driver hide the Allegro cursor when the
+ mouse moves out of our window.
+
+ 3.9.29: added a simple timer delay emulation of vsync() to the X code, so
+ that eg. the demo worms game runs sensibly.
+
+ 3.9.29: Isaac Cruz added a GFX_DIRECTX_WIN driver.
+
+ 3.9.29: Keith Gerdes made some more improvements to the DirectX overlay
+ driver.
+
+ 3.9.29: Andrew Geers added scrolling support to the grabber image viewer.
+
+ 3.9.29: Peter Wang added an alternative X DGA driver, that includes mode
+ switching support to run in fullscreen mode.
+
+ 3.9.29: Peter Wang added a MSG_WHEEL event to the GUI, and made
+ d_list_proc() use it.
+
+ 3.9.29: Lucas Vignoli Reis added a Portuguese (Brazil) message
+ translation and keyboard mapping.
+
+ 3.9.29: Peter Wang added a Linux OSS MIDI driver for FM synth devices,
+ and mixer support for the OSS digital driver.
+
+ 3.9.29: George Foot added scripts for building various Linux distribution
+ formats.
+
+ 3.9.29: Michael Bukin fixed the portability problems in quantize.c.
+
+ 3.9.29: added a zipwin.sh script for making Windows binary distributions,
+ including a batch file that can compile the MSVC support programs without
+ having any GNU tools installed.
+
+ 3.9.29: fixed bug with color font rendering in the Windows version.
+
+ 3.9.29: added hardware accelerated rectfill() and hline() to the Windows
+ version, and fixed a couple of accel related bugs (clears were being
+ clipped wrongly, and it was claiming to support XOR drawing even though
+ that isn't supported).
+
+ 3.9.29: Michael Bukin fixed bug with X drawing onto screen sub-bitmaps.
+
+ 3.9.28: various documentation updates.
+
+ 3.9.28: added parameter autodetection to the Unix OSS sound driver.
+
+ 3.9.28: made it possible to nest calls to the Unix for_each_file()
+ routine.
+
+ 3.9.28: added a load_datafile_callback() function.
+
+ 3.9.28: rationalised the sound config variables, so they can be shared
+ between drivers more easily. For instance sb_freq has been renamed to
+ sound_freq.
+
+ 3.9.28: Antti Koskipaa added a DOS driver for WSS (Windows Sound System)
+ cards.
+
+ 3.9.28: the audiosteam code is now able to merge multiple buffers into a
+ single larger one, so it will still work correctly even if the user
+ supplies a buffer smaller than the current soundcard transfer size. You
+ can even play streams with single byte buffers now, as long as you refill
+ them often enough!
+
+ 3.9.28: made the Windows timer code more robust, so it will no longer
+ lock up when you install extremely high frequency callbacks.
+
+ 3.9.28: Teijo Hakala added wheel support to the Windows mouse driver.
+
+ 3.9.28: Peter Wang added wheel support to the X mouse driver.
+
+ 3.9.28: Andrew Geers added -ppassword and -nosound options to the grabber.
+
+ 3.9.28: Keith Gerdes fixed the DirectDraw overlay mode driver.
+
+ 3.9.28: Isaac Cruz fixed the bug with accelerated drawing onto sub
+ bitmaps of DirectDraw surfaces.
+
+ 3.9.28: Peter Wang added banked mode support to the SVGAlib driver.
+
+ 3.9.28: Peter Wang fixed some problems with the ESD sound driver, and
+ added an ALSA driver.
+
+ 3.9.28: palette fading speed is now timer regulated, to avoid problems
+ with some systems (eg. DGA with non-matching color depth) where it can be
+ excessively slow.
+
+ 3.9.28: fixed a couple of different overflow bugs that were causing
+ timers to run slow on heavily loaded Unix systems.
+
+ 3.9.28: added a display of author credits to the demo game.
+
+ 3.9.28: changed the info page installation system. It now creates a dir
+ file in the same directory as the info page, rather than messing around
+ with symlinks, and autoconf is used to locate the install-info program.
+
+ 3.9.28: added an allegro-lib script to the Unix installation, which can
+ be run by makefiles to find the right linker commandline for building
+ Allegro programs.
+
+ 3.9.28: added a manpage output format to the makedoc utility. It doesn't
+ work terribly well with apropos due to the lack of a one-line summary for
+ each function, but the basic formatting seems to be ok: please let me
+ know if you see any problems.
+
+ 3.9.28: patches from George Foot for Linux console handing, keyboard, and
+ filename manipulations.
+
+ 3.9.28: many improvements by Michael Bukin, in particular enhanced
+ performance in X, better X mouse behaviour, and DGA graphics support.
+
+ 3.9.27: Robert J. Ragno made some improvements to the Wingman, PSX, and
+ throttle joystick input code.
+
+ 3.9.27: Peter Wang added wheel input support to the Linux mouse code
+ (this shows up as a new mouse_z state variable).
+
+ 3.9.27: Patrick Hogan made Windows audiostreams work properly.
+
+ 3.9.27: Sven Sandberg optimised the spline routines.
+
+ 3.9.27: Tomohiko Sugiura added KEY_YEN and KEY_YEN2 Japanese keys to the
+ input handler.
+
+ 3.9.27: Chris Robinson wrote a fixed point version of clip3d_f(), called
+ (surprise!) clip3d().
+
+ 3.9.27: Sven Sandberg improved the file selector sorting algorithm.
+
+ 3.9.27: Henrik Stokseth improved the OS detection in the Windows lib.
+
+ 3.9.27: Sven Sandberg made more accurately rounded lookup tables for the
+ fixed point trig routines.
+
+ 3.9.27: George Foot made the fbcon driver reset the palette on exit.
+
+ 3.9.27: much new X code from Michael Bukin: this stuff is working
+ brilliantly now!
+
+ 3.9.27: added the X library path to the Linux liballeg.a wrapper. I think
+ I prefer Michael's idea of having a script to return this info, though,
+ so perhaps we should change across to doing it that way.
+
+ 3.9.27: fixed various bugs in both the C and i386 RLE sprite code (mostly
+ relating to lit modes and hicolor formats).
+
+ 3.9.27: front-ported various fixes from the 3.12 release, to make
+ WARNMODE=1 compile cleanly with gcc 2.95.
+
+ 3.9.27: Knut Pape improved the Mingw32 readme file.
+
+ 3.9.26: rewrote the DOS Sidewinder driver, after powerjaw sent me a pad
+ to test it with. It still doesn't work for me in DOS mode, but it is ok
+ under Windows, which is better than before, and as good as any of the
+ other Sidewinder code that I've been able to locate. If anyone has or
+ knows of code that works better than this, please let me know!
+
+ 3.9.26: more flexible mode flags for set_color_conversion().
+
+ 3.9.26: Robert J. Ragno added a driver for Gravis GrIP devices.
+
+ 3.9.26: Stepan Roh updated the Czech translation and added multiple
+ codepage support to the textconv utility, and a Unicode-aware ustrtod()
+ function.
+
+ 3.9.26: added ustrdup() to the Unicode support functions.
+
+ 3.9.26: Sven Sandberg optimised the gcc fixed point math routines to
+ collapse constant expressions at compile time.
+
+ 3.9.26: Stefan T. Boettner added a proper Linux SVGAlib driver.
+
+ 3.9.26: several tweaks from Vincent Penquerc'h (added a datafile merge
+ function to the grabber, GUI bugfixes, optimised spline calculation, fix
+ for 24 bit version of the C drawing code).
+
+ 3.9.26: Linux patches from Michael Bukin improve the OSS sound driver,
+ SIGALRM handling, and X keyboard driver.
+
+ 3.9.26: many Linux patches from George Foot (fixes to the mouse driver,
+ shared library and configure script, and assorted other stuff).
+
+ 3.9.25: fixed pckeys.c to leave sensible data in the key[] array when
+ doing numeral vs. arrow key numlock fakery.
+
+ 3.9.25: fixed a bunch of problems with the SWITCH_BACKGROUND mode (I'd
+ stupidly forgotten to disable a lot of graphics driver functions that
+ could do bad things if called when the Allegro console isn't active).
+
+ 3.9.25: added pivot_sprite() and pivot_scaled_sprite() functions (thanks
+ to Matt Jallo for the suggestion).
+
+ 3.9.25: added ustrerror() to the standard Unicode support functions.
+
+ 3.9.25: fixed the d_edit_proc() GUI object to handle shift+tab focus
+ movement properly.
+
+ 3.9.25: lots of Linux patches from George Foot (proper fbcon mode
+ setting, different mouse types and setup program support for configuring
+ them, fixes to the shared library support, exedat no longer destroys the
+ file permissions, and probably some other stuff that I forgot about).
+
+ 3.9.24: assorted bugfixes to the Linux fbcon and sound code (this is
+ mostly an emergency release because these were broken in 3.9.23).
+
+ 3.9.24: James Arthur wrote some docs for the Photoshop-style truecolor
+ blender routines.
+
+ 3.9.23: Michael Bukin added an OSS sound driver to the Linux code, and
+ the beginnings of an ESD driver.
+
+ 3.9.23: many Linux patches from George Foot, including shared library
+ support.
+
+ 3.9.23: Ole Laursen made the Unicode utolower() and utoupper() functions
+ understand the entire 16 bit character set.
+
+ 3.9.23: Pavlos Touboulidis made file_select() able to include or exclude
+ files based on their attributes.
+
+ 3.9.23: the d_check_proc() GUI object can now print the text to the right
+ of the check, selected by having a non-zero d1 field.
+
+ 3.9.23: changed my mind about how GFX_SAFE should work, and removed the
+ color depth emulation bodges. Now, the GFX_SAFE driver may simply change
+ the color depth if it doesn't like what you are requesting, and it is up
+ to the caller to deal with this.
+
+ 3.9.23: fixed problems with MMX polygon rendering code in the MSVC
+ version.
+
+ 3.9.23: added a strictwarn option to the configure script, and fixed
+ everything that it moaned about. The warnings still aren't all that
+ strict: at some point I want to sit down and make it build cleanly with
+ -W, as well as -Wall -Werror.
+
+ 3.9.22: fixed some potential race conditions introduced by my previous
+ fixes to the Windows timer code.
+
+ 3.9.22: made set_display_switch_callback() able to install multiple hook
+ functions, added a remove_display_switch_callback() routine, and wrote an
+ exswitch example program.
+
+ 3.9.22: adjusted MSVC inline asm syntax in an attempt to work around
+ compiler version conflicts.
+
+ 3.9.22: more flexible GFX_SAFE system. As well as defining fixed safe
+ values for each platform, you can now leave out those definitions to get
+ zeros passed through to the actual hardware drivers, and if your driver
+ sets a color depth other than the requested one, graphics.c will hook up
+ some emulation routines so that everything still works in a sensible way.
+
+ 3.9.22: George Foot added a scancode to ASCII conversion function to the
+ keyboard driver (implemented for DOS, Windows, Linux, and X). This is
+ needed to handle alt+key input sensibly when using unusual mappings like
+ the Dvorak layout.
+
+ 3.9.22: Linux patches from George add better console switching, shared
+ library support, and various other nice things.
+
+ 3.9.22: Windows patch from Stefan adds much cool new stuff, including
+ windowed mode support.
+
+ 3.9.22: Peter Wang made the Linux GGI driver work properly.
+
+ 3.9.22: Johan Venter made some more improvements to the RSXNT and Mingw32
+ makefiles.
+
+ 3.9.22: updated the Watcom makefile to allow manual override of the 10.6
+ vs. 11.0 version detection, in case it guesses wrong.
+
+ 3.9.21: Windows patch from Stefan adds support for the new screen mode
+ switching system.
+
+ 3.9.21: more BeOS patches from Jason Wilkins.
+
+ 3.9.21: Johan Venter fixed some problems with the RSXNT and Mingw32
+ makefiles.
+
+ 3.9.21: ran "configure --enable-asm=no", and fixed all the reasons why
+ this didn't work. In particular there was a bug in patterned drawing
+ modes, RLE sprites were broken, and I'd forgotten to add C versions of
+ the RGBA sprite functions. Those of you who are interested in such things
+ will be interested to know that the test program thinks the C drawing
+ code is 20% slower at hline(), 10% slower at rectfill(), 50% slower at
+ blitting, and 40% slower at draw_sprite(), which is not at all bad going.
+ It's actually a bit faster at drawing translucent and lit sprites, so we
+ need to have a look at that!
+
+ 3.9.21: many new Linux patches from George Foot.
+
+ 3.9.21: added VBE/AF support to the Linux code.
+
+ 3.9.21: finished the Linux fbcon driver.
+
+ 3.9.21: made Linux console switching work in a more complete manner, with
+ a set of helper functions in dispsw.c. The background mode should work
+ now, but is untested.
+
+ 3.9.21: added Linux GGI driver by Carsten Schmidt (this is somewhat out
+ of date, and doesn't work yet, but a good start if anyone wants to hack
+ on it).
+
+ 3.9.21: improved the Unix configure and build system. Moved more things
+ into makefile.lst, so there are no file lists anywhere else now. Made it
+ understand how to build the datafile tools, and convert the documentation
+ (this may cause problems for systems without makeinfo: it would be good
+ if someone who groks autoconf could try to do this better). Made the
+ Linux VGA drivers (vga and modex) configurable.
+
+ 3.9.21: added ctrl+alt+end abort sequence to the Linux keyboard driver.
+
+ 3.9.21: directory structure changes: moved ufile.c into the misc
+ directory, so BeOS can share it. Moved various helper scripts into the
+ misc directory, including a cmplog.pl that compares two test.exe profile
+ logs.
+
+ 3.9.21: made the Linux PS2 mouse driver understand the middle button.
+ Added a scaling factor to make it go at a more sensible speed in SVGA
+ modes.
+
+ 3.9.20: started working on a driver for the Linux fbcon device. It works,
+ but can't change video mode yet.
+
+ 3.9.20: Windows patch from Stefan adds joystick input, and the beginnings
+ of a windowed mode driver.
+
+ 3.9.20: moved all filename lists (even the platform specific ones) into
+ makefile.lst, to avoid any duplication and give us a nice centralised
+ place that mentions every single source file we use.
+
+ 3.9.20: removed the install_lost_bitmap_callback() function, in favour of
+ the more generic set_display_switch_mode(). Updated the Windows code to
+ use these new routines.
+
+ 3.9.20: merged X patch from Michael Bukin (adds mouse support).
+
+ 3.9.20: Vincent Penquerc'h optimised the 256 to truecolor graphics
+ blitting code to avoid repeated conversions of the palette table.
+
+ 3.9.20: James Hyman added quoting support to get_config_argv().
+
+ 3.9.20: Peter Cech optimised the alpha sprite blending routines. Shawn
+ optimised them a bit more by expanding out specialised versions for
+ common pixel formats.
+
+ 3.9.20: Richard Davies made some improvements to the PSX joypad driver.
+
+ 3.9.20: added a system driver parameter to allegro.cfg, and hooks to make
+ the Unix version look for config data in /etc/ and ~/.
+
+ 3.9.20: moved the Posix findfirst() emulation into libc.c, removing it
+ from the autoconf and BeOS specific builds.
+
+ 3.9.20: more BeOS patches from Jason Wilkins. The graphics stuff be
+ working there now!
+
+ 3.9.20: improved the VBE/AF driver to know that vertical lines can be
+ implemented as a rectfill. This enables hardware acceleration for
+ patterned vertical lines, and with drivers that don't have hardware
+ support for the VBE/AF line draw routine.
+
+ 3.9.20: George Foot did some major work on the Linux console version,
+ getting it up and running in a fairly convincing way.
+
+ 3.9.20: the Windows sound driver lists are now dynamically generated
+ based on the available devices, so you can select which ones to use.
+
+ 3.9.19: wrote the first part of an Allegro Hacker's Guide, which is my
+ (probably futile :-) attempt to document at least a few of the more gory
+ parts of the Allegro code.
+
+ 3.9.19: finally got around to documenting the Unicode functions.
+
+ 3.9.19: more BeOS patches from Jason Wilkins.
+
+ 3.9.19: Michael Bukin made some more patches to the X code (timers are
+ implemented now), and added a complete (?) C implementation of all the
+ drawing code. Non-Intel machines, here we come! If you define
+ ALLEGRO_USE_C before building the djgpp library, you can actually test
+ out a pure C version of test.exe, the demo game, etc.
+
+ 3.9.19: added a findtext.sh script, which scans the source code and
+ creates a list of all the strings that are available for translation. It
+ can also compare this list against an existing translation file, to see
+ if any new messages need to be added.
+
+ 3.9.19: Stepan Roh updated the Czech keyboard mapping for Unicode
+ support, added support for keyconf to use a non-standard font, and added
+ the Latin Extended-A characters (U+0100 to U+017F) to the default font.
+
+ 3.9.19: Grzegorz Adam Hankiewicz updated the Spanish translation with
+ UTF-8 format (ie. properly accented) strings. Converted the setup program
+ font into Latin-1 ordering so that this will display correctly. Fixed bug
+ with dat2s not correctly converting the resulting multiple-range font.
+
+ 3.9.19: Chris La Mantia made some cosmetic fixes to the d_slider_proc()
+ GUI object.
+
+ 3.9.19: Richard Davies added support for N64 joypads.
+
+ 3.9.19: added keyboard_ucallback() (I missed this one when I first added
+ the Unicode support).
+
+ 3.9.19: made some changes to setup.c so that it can easily be embedded
+ into other programs (thanks to Grzegorz Adam Hankiewicz for the
+ suggestion).
+
+ 3.9.18: added support for 32 bit RGBA images. You can now read TGA files
+ with an alpha channel into the grabber, or you can import a normal image
+ and then overlay alpha data from any greyscale bitmap. You can save these
+ alpha channels as part of a datafile, call the makeacol(r, g, b, a)
+ function, and most importantly, call set_alpha_blender() and then
+ draw_trans_sprite() to display them. Check out exalpha.c. There is much
+ room to optimise the 15, 16, and 24 bit versions of _blender_alpha*(), if
+ anyone wants to have a go at this. I think it would be profitable to
+ write specific versions for common pixel orderings, and only keep the
+ current generic implementation around as an emergency fallback.
+
+ 3.9.18: more Unix patches from Michael Bukin. It builds flawlessly now,
+ even if it doesn't do anything very interesting yet.
+
+ 3.9.18: Jason Wilkins contributed the beginnings of a BeOS port (not yet
+ functional, but it does compile).
+
+ 3.9.18: Revin Guillen added a position_dialog() function.
+
+ 3.9.18: portability improvements: changed makefile to be a generated
+ stub, which normally just includes makefile.all, but can be completely
+ replaced when using autoconf, and moved the emulation for missing libc
+ functions into the shared sources.
+
+ 3.9.18: numerous bugfixes.
+
+ 3.9.17: Burton Radons changed the truecolor pixel blending functions to
+ use a single callback function rather than the previous table. This may
+ break some old code, but should remain largely backward compatible, and
+ the new way is much more flexible. He also added a more complete set of
+ blender functions, including Photoshop modes like burn, difference,
+ lumincance, etc.
+
+ 3.9.17: Richard Davies added support for PSX joypads.
+
+ 3.9.17: fixed bug in dat2s handling of truecolor images.
+
+ 3.9.17: Jason Wilkins improved the quaternion math routines, and added
+ some documentation for them.
+
+ 3.9.17: Neil Townsend added callback parameters to the timer handlers.
+
+ 3.9.17: Gunter Ladwig added three-button mouse emulation, which can be
+ enabled using the config file (it defaults to on if you have a two button
+ mouse).
+
+ 3.9.16: applied some patches from Michael Bukin, which add the basics of
+ a Unix build system. It doesn't actually work yet, though :-)
+
+ 3.9.16: merged new code from Stefan. Lots more cool things are working in
+ the Windows version now, eg. hardware acceleration, triple buffering,
+ sound...
+
+ 3.9.16: added an example of how to write a Windows screensaver using
+ Allegro. If anyone knows how to get a proper name to show up in the
+ Windows selection dialog, please let me know! (I've made the stringtable
+ entry that MSDN says you need, but it doesn't work).
+
+ 3.9.16: Andy Goth added a d_text_list_proc() dialog object, that lets you
+ alter the selection by typing the first few characters of a list entry.
+
+ 3.9.16: Ole Laursen updated the Danish message translation.
+
+ 3.9.16: Calvin French added a -w (always update) switch to dat.exe.
+
+ 3.9.16: Joerg Rueppel added more flexible wildcard matching for object
+ names in dat.exe.
+
+ 3.9.16: added GFX_HW_SYS_TO_VRAM_BLIT and GFX_HW_SYS_TO_VRAM_BLIT_MASKED
+ capabilities flags, and more flexible blitting functions in the vtable.
+
+ 3.9.16: added lock_voice() and unlock_voice() methods to the digital
+ sound driver, for implementing audiostreams under Windows.
+
+ 3.9.16: _handle_timer_tick() now returns the desired gap until the next
+ interrupt.
+
+ 3.9.15: Michael Rickmann added a Mingw32 port. This currently works the
+ same way as the RSXNT version, using MSVC to build the DLL, but will
+ become a full gcc port after the core Windows code stabilises a bit.
+
+ 3.9.15: Vincent Penquerc'h added a D_DIRTY flag for GUI objects, and I
+ extended this with a new D_REDRAWME return code for the handlers.
+
+ 3.9.15: changed the syntax of the create_color_table() callback. This
+ breaks the API, but is the only way to make it work reliably with
+ different compiler calling conventions.
+
+ 3.9.15: added a sub bitmap creation hooks to the vtable structure (so the
+ parent bitmap can be told when it is being cloned).
+
+ 3.9.15: "make install" is now a separate target, not run automatically.
+ This means that you now have to run "make" and "make install" as two
+ separate operations, or if you want all three versions of the library,
+ "make all" and then "make installall".
+
+ 3.9.15: added an END_OF_MAIN() macro, which makes the WinMain() magic
+ work correctly in any combination of C and C++ code.
+
+ 3.9.15: Olly Betts modified the djgpp makefile to support cross-compiling
+ on a Linux machine.
+
+ 3.9.15: Andy Goth added a 256x256 tweaked VGA mode.
+
+ 3.9.15: major documentation update (from now on I'll be adding a version
+ number to each changelog comment).
+
+ Merged new code from Stefan. Windows version is getting much closer to
+ completion, including mouse support and video bitmaps, although the mouse
+ code isn't working quite right for me at the moment.
+
+ Rewrote fix_filename_path() to avoid calling _fixpath(). The new version
+ is much more portable, although things like reading the current directory
+ across multiple drives need some tweaking to work with different
+ compilers.
+
+ Fixed oodles of things that were stopping the Watcom version from
+ working. It now runs everything without any trouble at all, including
+ such gems as exdodgy and the grabber shell edit! According to test.exe,
+ gcc 2.8.1 is about 10% faster than Watcom 10.6 for most things, although
+ for some reason textout() is about twice as fast in the Watcom version.
+
+ Fixed a bunch of stuff to make the RSXNT version work. All the tests and
+ examples now build with RSXNT, and work identically to the MSVC originals.
+
+ Added quaternion math routines by Jason Wilkins.
+
+ Added more flexible gfx_card config support by Andy Goth.
+
+ Added a masked_stretch_blit() function (trivial change, the code could do
+ it, but the API entry point was missing).
+
+ Added Windows GDI routines by Marian Dvorsky.
+
+ Added a DMA poll to the Soundscape driver, to make sure it can never get
+ out of sync with the transfer.
+
+ Merged various bits and pieces that have been sitting around my hard
+ drive for ages (Swedish and Norwegian translations, various patches from
+ Michael Bukin, new palette generation code by Michal Mertl, Soundscape
+ driver fixes by Andreas Kluge).
+
+ Grabber now knows about and can manipulate Unicode fonts.
+
+ Now passing atexit() as a parameter to install_allegro(), to avoid
+ problems with DLL shutdown.
+
+ Made FLIC player set the dirty variables when clearing the bitmap at the
+ start/loop point (this was sometimes causing the screen not to be cleared
+ from previous contents).
+
+ Fixed several bugs in the grabber.
+
+ Changed the datafile utilities to link the datedit and plugin routines as
+ a proper library. This will make life easier for third parties that want
+ to use those routines (duplicating the plugin linkage isn't much fun).
+
+ Replaced errno references with allegro_errno pointer, to avoid problems
+ with multiple runtimes when linking as a DLL. The MSVC version of dat now
+ works perfectly!
+
+ Added a system_none driver for commandline utilities and other platform
+ neutral situations.
+
+ Made new demo intro animation. My first ever Max rendering!
+
+ Merged Windows patches from Stefan. Whoah! This thing is cool. It works
+ (sort of :-) on two platforms. Now I can die happy....
+
+ The file selector now adjusts for platforms without any directory list
+ (eg. Unix).
+
+ Added a global default_palette (the normal IBM BIOS one), and made
+ set_gfx_mode() select it.
+
+ Modified DIGMID driver to avoid using 64 bit ints or floating point in
+ the interrupt handler.
+
+ Added ASSERT() and TRACE() debugging routines, and lots of asserts
+ throughout the library code.
+
+ The default truecolor pixel format before setting a video mode is now BGR
+ rather than RGB. This should help to shake out bugs in BGR support, and
+ catch any errors where people load graphics before setting a video mode.
+
+ Fixed fmul() overflow detection bug.
+
+ Rewrote gpro.c and sw.c to avoid using inline asm. The SW code is
+ currently very ugly (literal translation of the asm routine), but I'm
+ keen to improve it given some testing feedback. If you have a Gamepad Pro
+ or Sidewinder, and were able to use it with the Allegro 3.11 driver, I
+ would _really_ like to hear whether this current code works for you or
+ not...
+
+ Numerous changes to make the support programs more portable.
+
+ Added a get_executable_name() function.
+
+ The sound.cfg file is no longer supported. Use allegro.cfg instead.
+
+ Added versions of the inline _putpixel() and _getpixel() for all color
+ depths.
+
+ The check_cpu() function is now called automatically by allegro_init().
+
+ Added system bitmap objects, which exist in system memory but are
+ accessed in a similar way to video memory surfaces (this can enable
+ better hardware acceleration on some platforms).
+
+ Added enable_triple_buffer(), timer_can_simulate_retrace(), and
+ timer_is_using_retrace() functions. This enables programs to correctly
+ handle the interrelationship between mode-X triple buffering, the retrace
+ sync mode, and the current OS, without having to include any DOS specific
+ code.
+
+ GUI routines now call the input polling functions and acquire/release the
+ screen as appropriate.
+
+ Fixed a real show-stopping error that was causing VBE/AF crashes on some
+ machines (calling driver functions with non-flat memory selector in %es).
+
+ Added an allegro_message() function.
+
+ Added dummy bank switch routines that can emulate linear access to a
+ mode-X screen, albeit rather slowly. The only practical result from this
+ is that polygon routines work in mode-X now, but it helps to make things
+ more robust in general (if a routine doesn't know about mode-X, now it
+ will just run more slowly than usual, rather than not working at all).
+
+ The SB, Adlib, and standard joystick drivers now properly have a separate
+ instance for each variant of the hardware, rather than a single driver
+ pretending to exist under multiple different ID codes.
+
+ Rewrote joystick polling to avoid inline asm.
+
+ Converted translation files into UTF-8 format. These can now use any
+ Unicode characters they like, so accented vowels etc. can safely be used.
+
+ Keyboard scancodes have changed from the hardware format to an abstract,
+ Allegro-specific encoding. This simplifies the code a great deal, and
+ avoids hassles with two different keys generating the same scancode.
+
+ Added generic find_allegro_resource() function, which removes a lot of
+ duplicated code from config.c, digmid.c, and pckeys.c.
+
+ Timer module now autoinstalls whenever someone tries to use it.
+
+ Keyboard functions can now alter the repeat rate.
+
+ Watcom port.
+
+ Added a special GFX_SAFE driver ID.
+
+ Now using VDS to detect win95 even when in stealth mode.
+
+ Added fixver.sh for patching version numbers and dates when releasing a
+ new version (requires bash, fileutils, shutils, etc, to run on DOS).
+
+ Added zipup.sh for building a distribution zip and diffs, which
+ automatically cleans up the tree ready for this (eg. pregenerating the
+ dependency files for all supported compilers).
+
+ Added input polling functions.
+
+ Major code restucturing, added system drivers, new framework for input
+ handling, timers, keyboard scancode conversion, file access, etc.
+
+ Added full support for Unicode text, including string manipulation
+ functions, a new font format, the textconv utility, a new GUI MSG_UCHAR,
+ and a ureadkey() function.
+
+ Added variable sized monochrome fonts, replacing the the old 8x8 fixed
+ size format. As a result, the GFX_HW_TEXTOUT_FIXED capabilities flag has
+ been renamed to GFX_HW_GLYPH.
+
+ New system for accessing video memory, using bmp_select(), bmp_write*(),
+ and bmp_unwrite_line(). This is equivalent to the djgpp farptr functions,
+ but portable to different platforms.
+
+ Drastic reorganisation of directory structure, makefile system, etc.
+
+ Enhanced the makedoc utility to simplify adding links and email addresses
+ to the docs.
+
+ Added a bodge to make the VESA code work with broken S3 Trio64 drivers.
+
+ Removed the 386DX vs. 386SX processor detection code (it was sometimes
+ crashing).
+
+ Cleaned up a few places where memory wasn't getting freed during the
+ system shutdown. A cosmetic detail since the OS will free it for us, but
+ it is nice to get these things right.
+
+ Alessandro Monopoli added an Italian translation of the system messages.
+
+ Henrik Stokseth added code to distinguish between win95 and win98.
+
+ Creative Labs have been removed from the THANKS file, because of their
+ refusal to release any specs on the SB Live soundcard.
+
+ Changed the name of the library. After years of thinking that Allegro was
+ a word with no particular meaning, I realised that it is in fact a
+ recursive acronym for "Allegro Low Level Game Routines".
+
+ Established a new mailing list for use by the people currently working on
+ Allegro. Please send code contributions to this list rather than directly
+ to me (Shawn Hargreaves), because this will allow Allegro development to
+ continue even if I'm not around or am busy with something else at the
+ moment.
+
+ Andreas Kluge wrote a driver for Ensoniq Soundscape cards.
+
+ More localisation: Swedish message translation by Sven Sandberg, Anton
+ Ragnarsson, and Erik Sandberg, Finnish message translation by Antti
+ Haapala, and Russian message translation and keyboard mapping by Dmitriy
+ Kazimirow.
+
+ The midi_out() function now correctly updates the pan/volume/bend
+ controller status.
+
+ Kester Maddock added a Wingman Warrior joystick driver.
+
+ Fixed some problems with the Sidewinder, Gamepad Pro, and SNES joypad
+ drivers.
+
+ Changed the SB16 driver to use signed 16 bit output mode, rather than the
+ previous unsigned format. Hopefully this will improve compatibility with
+ crappy clone hardware.
+
+ Added a new WARNMODE environment switch to the makefile. Allegro
+ developers should all set this to get strict warnings, but it will be
+ left off by default so that the distributed version will be more
+ forgiving about different compiler/libc versions.
+
+ Fixed problem with reading the top and left positions on digital joystick
+ devices.
+
+ Fixed (I think, still waiting accurate confirmation on this one :-)
+ problem with timers running too fast on some motherboards.
+
+ Fixed stupid bug where get_align_matrix() wasn't bothering to zero the
+ translation vector.
+
+ Fixed stupid bug where rotated sprites were coming out upside down in
+ mode-X and hi/truecolor modes.
+
+ Fixed bug where dat utility was truncating long filenames to 8.3 format.
+
+ Renamed the ChangeLog file to CHANGES, to avoid problems on 8.3 systems.
+
+ Changes between the 3.1 beta and final releases: assorted bugfixes,
+ Antoine Mathys added a Swiss keyboard mapping, Thomas Wolf added a German
+ translation of the system messages.
+
+ Changes between the 3.1 alpha and beta releases: assorted bugfixes, FLIC
+ routines can now read from datafiles, included rotation optimisations by
+ Ivan Baldo.
+
+ Peter Cech added support for hot-swapping between a custom keyboard
+ layout and the standard US mapping.
+
+ Neil Townsend improved the accuracy of the timer routines.
+
+ Added exlights.c example program, showing one way to do colored lighting
+ effects in a hicolor mode (and also because it makes the total number of
+ examples a nice round number :-)
+
+ Added an afinfo test program, which does the same thing as vesainfo but
+ for VBE/AF drivers.
+
+ Michael Bukin made a lot more portability patches and some bug fixes,
+ including some improvements to the FLIC player and a much more rational
+ filename handling system.
+
+ Removed the chipset-specific SVGA hardware drivers from the main library
+ distribution. Instead, these will now be available both as an optional
+ addon package, and reformatted as part of the FreeBE/AF project.
+
+ Added FreeBE/AF extensions support to the Allegro VBE/AF driver (farptr
+ access to video memory, and the libc and pmode exports needed for future
+ compatibility with the SciTech Nucleus drivers).
+
+ Fixed a bug with the patterned and translucent vline() function in 15 bit
+ color depths.
+
+ Fixed a NULL pointer dereference bug in the config routines.
+
+ Fixed an order of processing bug that was causing data to be lost when
+ calling set_config_file() with the same filename as the current config.
+
+ Stepan Roh added a Czech translation of the system messages.
+
+ Ole Laursen added a Danish translation of the system messages.
+
+ Grzegorz Ludorowski made a new demo game intro animation.
+
+ Calin Andrian added 3d polygon timing routines to test.exe.
+
+ Peter Cech added grabber support for the 8x8 BIOS font format.
+
+ Stepan Roh added a Czech keyboard mapping.
+
+ Renamed the Spanish language translation file from SP to ES.
+
+ Calin Andrian added a complete set of truecolor polygon rendering
+ routines, with support for MMX and 3DNow! optimisations and a new masked
+ lit drawing mode, along with a new polygon clipping function. One minor
+ change is that POLYTYPE_FLAT mode is now implemented by calling hline(),
+ so it will respond to the current drawing_mode() settings.
+
+ Changed the graphics/sound/joystick driver ID numbers from a zero based
+ list to a descriptive 4-character string, to make them more readable and
+ flexible. Added config functions to read/write data in this format. The
+ sound config data is backwardly compatible, but you will need to manually
+ update any graphics or joystick driver numbers that are stored in your
+ config files.
+
+ Michael Bukin contributed a _lot_ of patches to improve the portability
+ and robustness of pretty much the entire library. The only externally
+ visible change is that the macros used for declaring hardware driver
+ lists have been redesigned to use a more portable syntax, although the
+ old syntax is still available as a compatibility macro.
+
+ Burton Radons did some more optimisation of the truecolor pixel blending
+ functions.
+
+ Martijn Versteegh added a hook mechanism for extending the config file
+ system, which can be used to provide extended system status information
+ or customisation routines for addon packages.
+
+ Redesigned the grabber and dat utilities to support source-code "plugin"
+ modules, which can be used to extend the system with additional object
+ types, import/export routines, and menu commands.
+
+ Ivan Baldo added a dithering option to the 15/16 bit color conversion
+ routines.
+
+ Kerry High added a SNES joypad driver.
+
+ Added a font override to the d_text_proc() and d_ctext_proc() GUI
+ objects, using the dp2 field to specify a custom font.
+
+ Michael Tanczos fixed some bugs in the FLIC player.
+
+ Cloud Wu optimised the truecolor pixel blending functions.
+
+ Paul Pinault added a French translation of the system error messages.
+
+ Grzegorz Adam Hankiewicz added a Spanish translation of the system error
+ messages, and added a new (but undocumented :-) command line option to
+ the demo game.
+
+ Fixed clicks in the interpolated sample mixing.
+
+ Fixed a bug with position_mouse() not updating the mouse_pos variable.
+
+ Fixed a bug in mode-X horizontal scrolling while the timer retrace
+ simulator is active.
+
+ Added a language.dat file, which can be used to provide translated
+ versions of system strings (eg. error messages), in a similar way to the
+ existing keyboard.dat. If you want to use this mechanism from your own
+ code, replace all your constant strings with calls to
+ get_config_text("string"). This allows them to be translated by including
+ a line of the form "string=foreignstring" in the relevant section of
+ language.dat.
+
+ Added an ASCII name field to the keyboard mapping files, in order to make
+ the setup program a bit more friendly.
+
+ Increased the maximum number of sound channels from 32 to 64.
+
+ Modified the DIGMID patch loader to support 16 bit samples, rather than
+ just reducing everything to 8 bit.
+
+ Added an interpolation option to the sample mixer (quality=2).
+
+ Salvador Eduardo Tropea added support for proper 16 bit sample mixing
+ (quality=1).
+
+ Lee Killough added a lower level hook routine to the keyboard handler.
+
+ Removed floating point code from the DIGMID driver, to avoid potential
+ FPU stack overflows.
+
+ Jim Flynn removed floating point calculations from the AWE32 MIDI driver
+ (these could sometimes cause stack overflows).
+
+ Salvador Eduardo Tropea improved the datafile system to avoid linking of
+ unused code.
+
+ Romano Signorelli contributed a Bresenham arc plotting function.
+
+ Thomas Wolf corrected some errors in the German keyboard mapping file.
+
+ Grzegorz Adam Hankiewicz improved the excolmap example program.
+
+ Sven Sandberg optimised the fixed point trig routines.
+
+ Fixed some silly crash bugs in the joystick code.
+
+ Added a "compress" target to the makefile, based on a suggestion
+ by Grzegorz Adam Hankiewicz.
+
+ Added dummy bitmap acquire/release functions to allegro.h, for
+ compatibility with the Windows version.
+
+ Added a cross-reference facility to the Info format documentation.
+
+ Martin Fuller fixed an obscure bug in the reading of compressed .bmp
+ files.
+
+ The emergency exit signal handler now correctly restores the previous
+ handler, rather than resetting to the default action.
+
+ Sven Sandberg optimised the create_light_table() function.
+
+ George Foot fixed a bug when the get_mouse_mickeys() routine was called
+ with both parameters pointing to the same value.
+
+ Changed the licensing terms from "swapware" to "giftware". See the
+ Allegro website for an explanation of the reasons for this change.
+
+ Added yet more overloaded operators (this time for long and double types)
+ to the fix class.
+
+ Marius Fodor added support for the Sidewinder and Gravis GamePad Pro.
+ Many apologies for my taking so long to merge in this code!
+
+ Stefan Schimanski optimised the reverse blitting routine (for overlapping
+ images).
+
+ Added a shift+tab reverse focus movement key to the GUI routines.
+
+ Grzegorz Adam Hankiewicz added a new example showing how to create and
+ use a custom color mapping table.
+
+ Totally revamped the joystick system (better API and new driver
+ structure).
+
+ Modified the fix class to work properly with gcc 2.8.0.
+
+ Added a help.txt "how to get tech support" file.
+
+ The midi_pos variable is now negated, rather than cleared to -1, at the
+ end of a MIDI file. This can be used for measuring the length of a file.
+
+ Added a rendering hook to the font structure, for use by text addon
+ packages.
+
+ Improved the VBE/AF text output routine.
+
+ Corrected an error in the way the VBE/AF driver interprets hardware
+ cursor colors.
+
+ Pedro Cardoso contributed a tweaked 80x80 VGA mode.
+
+ The VBE/AF driver now supports dumb framebuffer drivers as well as
+ accelerated ones.
+
+ Added more accelerator support to the VBE/AF driver (hardware cursors,
+ lines, vertical lines, triangles, fixed width text output, and
+ opaque/masked blitting from system memory to the screen).
+
+ Added a scare_mouse() function, based on ideas by Martijn Versteegh.
+
+ The grabber now stores the "grab from grid" dialog state in allegro.cfg.
+
+ Sven Sandberg fixed a problem with save_bitmap() widths being rounded
+ upwards.
+
+ Made the _timer_installed flag globally visible.
+
+ Ove Kaaven added linear framebuffer support to the native mach64 driver.
+
+ Erik Sandberg optimised the 8 bit draw_sprite() and draw_trans_sprite()
+ functions.
+
+ Michal Mertl fixed a memory leak in the generate_optimized_palette()
+ function.
+
+ Added an ALLEGRO_DATE version define to allegro.h.
+
+ Michael Bukin optimised the line drawing routine and fixed problem with
+ the inline asm constraints for fadd()/fsub().
+
+ Fixed potential problems caused by a lag between the mouse state
+ variables changing and the pointer being redrawn.
+
+ Michal Mertl optimised the clipping code for lines, rectangles, and
+ circles.
+
+ Maiolino Carmelo contributed an Italian keyboard mapping.
+
+ Fixed lockup problems caused by the keyboard LED functions on some
+ platforms/hardware.
+
+ Added new create_video_bitmap() and show_video_bitmap() functions.
+
+ Added a profile option to the test program.
+
+ The keyboard handler now correctly updates the BIOS state for the right
+ control and alt keys when it shuts down.
+
+ Fixed a problem that was preventing the DIGMID driver from reading patch
+ sets stored in executable appended datafiles.
+
+ Changed the default sample priority from 255 to 128.
+
+ Fixed some problems with virtual screen sizes in the VBE/AF driver.
+
+ Added two new example programs.
+
+ The VBE/AF driver now has full support for hardware accelerated drawing.
+
+ Added VBE 3.0 support, including new triple buffering routines.
+
+ Wrote a routine to select the sound input source (microphone, line input
+ or CD audio).
+
+ Added proper support for stereo samples. This requires an extra parameter
+ to the play_audio_stream() function, so you will need to change any
+ programs that use this. I'm very sorry for breaking your old code!
+
+ Fixed bugs with the SB16 autodetection and 16 bit sample recording.
+
+ Added input support to the raw SB MIDI interface driver.
+
+ Wrote a new test program to demonstrate the audio input features.
+
+ Ove Kaaven added support for MIDI and audio (sampled sound) input.
+
+ The pack_fopen() function now understands nested datafiles as directory
+ structures, using filenames like "graphics.dat#level1/sprites/zdurgle".
+
+ Charles Mac Donald showed me how to set a 160x120 VGA mode, and more
+ reliable 400x* mode-X resolutions.
+
+ Guilherme Silveira and Theuzifan Sumachingun both independently modified
+ the file selector to only list valid drive letters.
+
+ Carsten Sorensen added a driver for the ESS AudioDrive soundcard.
+
+ Przemek Podsiadly added hicolor versions of the 3d polygon routines.
+
+ Ove Kaaven added truecolor support to the native ATI mach64 driver.
+
+ Patrick Hogan added a draw_gouraud_sprite() function.
+
+ Ben Chauveau added a driver for Tseng ET6000 cards.
+
+ Marco Campinoti added truecolor support to the native Tseng ET4000 driver.
+
+ Marco Marmulla added 16 bit support to the load_voc() routine.
+
+ Added Danish, Swedish, and Norwegian keyboard mappings.
+
+ Added GUI hook functions for scaling or offsetting the mouse position.
+
+ Fixed bug which was causing a lockup when calling set_leds(-1).
+
+ Michael Bevin optimised the create_trans_table() function.
+
+ It is now possible to display a mouse pointer without the mouse handler
+ needing to be installed.
+
+ Added a create_sample() function.
+
+ Made the _blender_map pixel blending functions and the _mouse_installed,
+ _keyboard_installed, and _sound_installed flags globally visible.
+
+ Added an 8-button joystick mode.
+
+ Chris La Mantia fixed a minor visual problem with the d_icon_proc().
+
+ Added a Rich Text Format (.rtf) version of the documentation.
+
+ Added postfix increment and decrement operators to the C++ fix class, and
+ the unary negation operator is now const-correct.
+
+ Merged in George's improved instrument parameters for the AWE32 driver.
+
+ The pat2dat utility can now reduce sample data from 16 to 8 bits (saves
+ space, and the DIGMID driver only uses 8 bits in any case).
+
+ Added yet another version of the mouse handler, this time in an attempt
+ to make it work more reliably under Windows NT.
+
+ Frodo Baggins added a mapping table for Portuguese keyboards.
+
+ Added an external tool "shell" function to the grabber.
+
+ Added a "box grab" function to the grabber, which uses a color #255
+ bounding box to determine the extent of the sprite to grab.
+
+ Santeri Saarimaa added a Finnish keyboard mapping.
+
+ Finished writing the pat2dat utility, and the DIGMID driver is working a
+ lot better now.
+
+ Mathieu Lafon added support for the Pause and PrtScr keys, and changed
+ the key[] array to a bitfield indicating whether either or both of the
+ normal and extended versions of the key are pressed. This remains
+ compatible with the "if (key[KEY_*])" syntax, but also allows you to
+ distinguish between, for example, the Enter key on the numeric pad and
+ the one next to the right shift key.
+
+ Fixed a bug in the handling of config variables that don't belong to any
+ section.
+
+ The makefile now tries to detect and warn people about some of the more
+ common installation errors.
+
+ The HTML version of the documentation now uses a short .htm file
+ extension if it is built on a system with LFN disabled.
+
+ Keyboard mapping files now only bother saving the entries that differ
+ from the default US mapping. This makes the maps a great deal smaller!
+
+ Changed the default font and keyboard mapping tables from DOS codepage
+ 437 to the standard ISO charset (first part of Unicode). If you have made
+ a keyboard config using the old codepage it will need to be updated, but
+ don't worry, I have a script that can do this very easily.
+
+ Fixed a bug in the detection of font formats (fixed or proportional) when
+ grabbing from a bitmap font.
+
+ Added an editable loop point to the MIDI player (thanks to George for
+ sorting out how to do this...)
+
+ Rewrote the mouse handler to track the position itself, using only the
+ mickey counters from the int 0x33 driver. Hopefully this will fix the
+ problem with buggy Logitech drivers...
+
+ Added a mouse_pos variable containing both the X and Y values in one 32
+ bit location, to allow a single instruction read during tight polling
+ loops.
+
+ The grabber now supports multiple selection, and has a new "ungrab"
+ command that copies from a bitmap object into the scratch buffer (you can
+ use this to generate palettes from truecolor images, or to re-grab a
+ smaller area from the image).
+
+ Added multiple selection abilities to the GUI listbox object.
+
+ Theuzifan improved the cpu detection for Cyrix chips.
+
+ Mathieu Lafon added a French keyboard mapping.
+
+ Richard Mitton wrote an example program demonstrating how to fake a 12
+ bit truecolor display on an 8 bit card.
+
+ Michal Mertl added a routine for generating optimised palettes for a
+ specific truecolor image.
+
+ Optimised the getr/g/b() functions. Converting between different color
+ depths should be much faster now...
+
+ Scott Harrison added code to detect OpenDOS, and use the i_love_bill mode
+ if their version of EMM386 is in use.
+
+ Added some new example programs.
+
+ The makedoc utility now converts between the DOS and Windows extended
+ character sets when producing HTML output files.
+
+ Ettore Perazzoli made a spectacular optimisation to the linear ->
+ mode-X blitting function.
+
+ Added a grid option to the dat utility, to specify which region of a
+ bitmap you want to grab.
+
+ Fixed a bug in blitting truecolor bitmaps onto mode-X destinations.
+
+ Fixed a bug that was preventing the Adlib volume from being changed when
+ only MIDI sound drivers were installed.
+
+ The grabber can now be run in video modes other than 640x480 (it doesn't
+ look very nice in lower resolutions, though :-)
+
+ Added a new fake scancode for the extended / key (the one on the numeric
+ keypad) so that the two keys can be distinguished from each other.
+
+ Joaquin Hierro Diaz made a mapping table for Spanish keyboards.
+
+ The setup utility can now be used to select a keyboard layout and to
+ calibrate the joystick, as well as for the sound hardware.
+
+ Moved some of the documentation to different locations, so hopefully
+ people will now be less likely to miss the faq.txt, and to bring it
+ closer in line with the standard GNU distribution format.
+
+ Better keyboard configuration system. There is now a proper utility for
+ setting up the mapping tables, the tables can be read from external
+ files, and it properly supports the alt-gr and accent escape keys.
+
+ Menu items can now be disabled, have check marks next to them, and
+ support right aligned text eg. for displaying keyboard shortcuts, there
+ is a new "void *dp" field in the menu structure, and the click callback
+ routines can now use the global pointer "active_menu" to determine which
+ option they were called by, if a single routine is shared by several menu
+ items.
+
+ Peter Palotas added an input callback to the keyboard routines, and event
+ flags to the mouse callback.
+
+ Added a -pal option to the dat utility.
+
+ Grzegorz Ludorowski made some new graphics for the demo game.
+
+ Moved some code to new files and added a bunch of macros so you can
+ remove unused graphics and sound drivers at link time.
+
+ Fabian Nunez added support for the Logitech Wingman Extreme joystick.
+
+ Chris La Mantia contributed a d_slider_proc() dialog object.
+
+ Sean Gugler added a routine for changing the keyboard LED state.
+
+ George Foot added pause and seek functions to the MIDI player.
+
+ Added the ability to append datafiles (in fact any files at all) onto the
+ end of your program executable.
+
+ Merged in the AWE32 driver. Long live George!
+
+ Can now read RLE compressed TGA files.
+
+ Added a mouse movement callback function (useful for detecting double
+ click events).
+
+ Stefan Eilert added support for dual joysticks.
+
+ Seymour Shlien contributed a routine for drawing justified text.
+
+ Krzysztof Krzyzaniak contributed a loader for .VOC sample files.
+
+ Added a rotate_scaled_sprite() function.
+
+ Now supports the Dvorak keyboard layout.
+
+ Salvador Eduardo Tropea added a 320x100 VGA mode.
+
+ Implemented translucent and lit sprite and RLE sprite drawing functions
+ for the truecolor modes.
+
+ Updated the sound setup utility.
+
+ The dat utility can now output makefile dependencies for automatically
+ rebuilding the file when any of the source data changes.
+
+ Fixed some problems with the RGB <-> HSV conversion functions.
+
+ Truecolor image loading and grabber support.
+
+ Phil Frisbie provided some code to detect the CPU type.
+
+ Michal Mertl added 24 bit graphics modes. Hurrah!
+
+ Added functions for playing streams of digital audio data.
+
+ Chris La Mantia contributed a bitmap icon GUI object.
+
+ Doug Eleveld added a text box GUI object, plus an improved help system
+ for the grabber.
+
+ Added support for UK and AZERTY keyboard layouts. More can easily be
+ added if you send me the appropriate scancode -> ASCII mapping tables...
+
+ Added get_align_matrix(), qtranslate_matrix(), and qscale_matrix()
+ functions.
+
+ Added a draw_character() function for using sprites as monochrome pixel
+ masks.
+
+ It is now safe to pass the same matrix as both input and output to the
+ matrix_mul() function.
+
+ Paul Bartrum contributed some ellipse drawing functions.
+
+ Added some callbacks to the MIDI driver, allowing you to hook your own
+ code into MIDI notes or marker events.
+
+ Added a function to measure mouse movement in terms of mickeys
+ (difference since the last call) as well as in absolute screen
+ coordinates.
+
+ VolkerOth made the d_edit_proc objects able to scroll, if the string is
+ larger than the available space.
+
+ Added the ability to distinguish between the left and right Control and
+ Alt keys.
+
+ Fabian Nunez added support for the extra keys on a Microsoft keyboard.
+
+ Added void *dp2 and void *dp3 fields to the dialog structure. This
+ ought not to break any existing code, but will let you store a lot more
+ data when creating custom objects.
+
+ The packfile functions can now directly open and read from datafile
+ member objects, using fake filenames in the form "filename.dat#obj_name".
+ This means that all the Allegro file access routines (eg. load_pcx() and
+ set_config_file()) can now read from datafile objects as well as separate
+ files.
+
+ Added miditest and digitest programs to allow more rigorous testing of
+ the sound routines and patch sets, and a vesainfo program to check which
+ video modes are available on any given card.
+
+ Jan Hubicka wrote a faster version of create_rgb_table().
+
+ The grabber now scales the bitmap preview if the image is too large to
+ fit onto the screen.
+
+ Jorrit Rouwe provided a new and much cooler set of FM instrument
+ definitions for the Adlib MIDI driver.
+
+ Added a function to load .IBK patch sets for use by the Adlib driver.
+
+ Added a wrapper allegro/ directory around the contents of the zip file,
+ so it can now be safely unzipped into the main djgpp directory.
+
+ Richard Mitton added support for 6-button joysticks.
+
+ Truecolor (15, 16, and 32 bit) graphics modes.
+
+ Vastly improved sound routines (more flexible API, now supports up to 32
+ simultaneous voices on the SB, sample-based MIDI playback driver, can
+ reverse samples, volume/pan/pitch sweep effects, MIDI commands can be
+ output on the fly as well as played from MIDI files, and lots of other
+ goodies).
+
+ It is now possible to update the status of GUI dialogs incrementally from
+ your own control loops, with an update_dialog() function, rather than
+ completely transferring control to do_dialog().
+
+ Compressed files (including grabber datafiles) can now be encypted with a
+ password.
+
+ Added a masked_blit() function, that skips zero pixels.
+
+ Added code to detect being run under Linux DOSEMU, and use the less
+ demanding version of the timer code if this is the case.
+
+ Added a standardised configuration mechanism. The format for saved
+ joystick calibration information has changed, so existing joystick files
+ are no longer valid.
+
+ Added a textprintf() routine, which uses a printf() style format string.
+
+ Added a TexInfo version of the documentation (thanks for the help,
+ Francois!)
+
+ Jonas Petersen added a save_bmp() function, and support for the OS/2 BMP
+ format.
+
+ TBD/FeR added tweaked 320x600 and 360x600 resolutions to the mode-X
+ driver.
+
+ Matthew Bowie added support for 4-button joysticks.
+
+ Dave Thomson added RGB <-> HSV conversion functions.
+
+ Added a 'freeze_mouse_flag' variable, that can be used to lock the
+ pointer to a specific position.
+
+ Added a 'key_led_flag' variable, that can be used to prevent the keyboard
+ LED's updating in response to the capslock, numlock, and scroll-lock keys.
+
+ The midi player now resets midi_pos to -1 when the music finishes playing.
+
+ Adrian Oboroc wrote an LBM loader.
+
+ Fonts can now contain characters above ASCII 127.
+
+ Chris Wigman made a better intro animation for the demo game.
+
+ Added translucency, color blending, and lighting routines (based on code
+ by Owen Embury and ideas by Nathan Albury).
+
+ Added 3d math and matrix manipulation functions.
+
+ Added texture mapped and gouraud shaded polygon drawers.
+
+ Tim Gunn contributed code for reading and writing TGA files.
+
+ Fixed clamping problems with rotating non-circular sprites.
+
+ Added scrollbars to the GUI listbox object.
+
+ Seymour Shlien wrote a bezier spline drawing function.
+
+ Added fixed point fadd() and fsub() functions, which check for overflow.
+
+ Added pack_fseek() and chunk manipulation functions to the file routines.
+
+ Improved datafile structure and grabber program.
+
+ Wrote a utility to convert grabber datafiles into linkable asm code.
+
+ Salvador Eduardo Tropea improved the keyboard routines (better handling
+ of extended scancodes, keyboard LED support, capslock and numlock, and
+ alt+numpad input).
+
+ Fixed the packfile functions and file selector to work with long
+ filenames under win95.
+
+ Seymour Shlien contributed a BMP reader.
+
+ Added a hook function to the keyboard code, allowing you to use the GUI
+ code without installing the keyboard handler.
+
+ Fixed a lockup caused by trying to access non-existent floppy drives.
+
+ Francois Charton wrote a driver for Paradise graphics cards.
+
+ Chris La Mantia contributed a radio button GUI dialog object and added a
+ D_DISABLED object flag.
+
+ Markus F.X.J. Oberhumer fixed the Video-7 scrolling function.
+
+ Converted the docs into HTML format.
+
+ Added code to detect Windows NT.
+
+ Mark Habersack added support for newer Trident chipsets.
+
+ Did some more work on the VBE/AF driver (it now works, but still doesn't
+ support accelerated hardware features).
+
+ Fixed bugs in the WAV sample reader and FLIC player.
+
+ Added special 'windows friendly' mode to the timer code. You can now even
+ run demo.exe under Windows 3.1!
+
+ Reorganised directory structure, to allow for a Linux version. The output
+ liballeg.a is now found in lib/djgpp.
+
+ Added support for 8x16 BIOS format fonts.
+
+ Fixed a problem with overflow when rotating large sprites.
+
+ Fixed a problem with restoring the text mode screen height after running
+ Allegro programs.
+
+ Mode-X support (thanks to Jonathan Tarbox and Dominique Biesmans for
+ suggesting and then helping to implement this).
+
+ Compiled sprites.
+
+ Jonathan Tarbox contributed an FLI/FLC player.
+
+ Added patterned drawing modes.
+
+ Added a vertical retrace interrupt simulator.
+
+ polygon() can now handle concave and self-intersecting shapes. I also
+ changed the parameters a bit. Sorry if this breaks your old code, but
+ it's more efficient the new way...
+
+ Added stretch_sprite().
+
+ Wrote a floodfill() routine.
+
+ More flexible palette fade routines.
+
+ Added set_volume() to the sound code.
+
+ David Calvin wrote a sound setup utility.
+
+ Improved the GUI. Added popup/dropdown menus, joystick input, three
+ button alert boxes, better handling of arrow key focus movement, a new
+ keyboard shortcut object (d_keyboard_proc()), and '&' markers in strings
+ to display keyboard shortcuts. The GUI can also now be used with fonts
+ other than the standard 8x8 default, by altering the global 'font'
+ pointer.
+
+ Fabian Nunez added support for the CH Flightstick Pro joystick (looks
+ cool: I want one :-) and 3-button mice.
+
+ The keyboard handler now responds to the state of the ctrl and alt keys,
+ and there is a new simulate_keypress() function.
+
+ Mark Wodrich added sub-bitmaps, which share their memory with a parent
+ bitmap but can be positioned anywhere within it, and have their own
+ clipping rectangles.
+
+ Mark also modified the mouse driver to double-buffer the pointer (so it
+ doesn't flicker any more), and added a set_mouse_sprite_focus() function.
+
+ Added set_mouse_range() and set_mouse_speed() functions.
+
+ Thanks (again) to Mark Wodrich, the grabber can now import GRX .FNT files.
+
+ The grabber can now make backups when saving datafiles, and it only
+ writes the datafile headers if their contents have changed, to prevent
+ unnecessary recompilation.
+
+ Added a text_height() function.
+
+ The fixed point inverse sin and inverse cos functions now use lookup
+ tables, which makes them a lot faster.
+
+ Reorganised the directory structure, added some example programs, and
+ improved the documentation.
+
+ Marcel de Kogel fixed some problems with the MPU-401 driver. It now
+ actually works :-)
+
+ Marcel also provided some better drum sounds for the Adlib driver.
+
+ Inlined the fmul() and fdiv() functions.
+
+ Much faster fsqrt(), taken from Arne Steinarson's fix-float library.
+
+ Added inline bmp_write_line(), bmp_read_line(), and _putpixel() functions.
+
+ The keyboard routines now support the emergency abort sequence
+ ctrl+alt+del, and there are signal handlers to make sure Allegro will
+ shut down cleanly if your program crashes.
+
+ Wrote new irq wrappers that can deal with reentrant interrupts.
+
+ Added joystick routines (based on code provided by Jonathan Tarbox and
+ Marcel de Kogel).
+
+ Moved some functions to different files and juggled things about so the
+ linker can do a better job. If you don't use the sound stuff, or don't
+ use any graphics functions, now they won't be linked into your executable.
+
+ Marcel de Kogel manged to locate my (embarrassingly stupid :-) mistake
+ which was preventing the VESA 2.0 linear framebuffer driver from working.
+
+ Various other performance enhancements and bug fixes.
+
+ Dropped all the Borland code. A couple of months ago I ran out of disk
+ space, and it was with great satisfaction the I executed the command
+ 'deltree /y c:\bc4'. It was a horrible compiler, and I'm glad it's dead.
+
+ Added SVGA support. As a result it no longer makes sense for
+ allegro_init() to put the system into mode 13h, so you will be in text
+ mode until you call set_gfx_mode().
+
+ Added sound code (background MIDI music and sample mixing).
+
+ Added support for proportional fonts (of any size) as well as the old 8x8
+ fixed size ones.
+
+ XOR drawing mode.
+
+ There is no longer such a thing as a SPRITE structure. The sprite drawing
+ code now draws bitmaps onto other bitmaps, which is a much more flexible
+ way of doing things. The datafile reader will convert all your old
+ sprites to bitmaps as it loads them in, so the only practical difference
+ this is likely to make is that the sprite drawing routines can't draw
+ opaque sprites any more (but you can use a blit instead).
+
+ show() and get_sprite() no longer exist: use blit() instead.
+
+ Added flipped and rotated sprite draw routines.
+
+ Added bitmap scaling.
+
+ Added RLE sprites.
+
+ drawsprite() has been renamed to draw_sprite().
+
+ textmode() has been renamed to text_mode(), to avoid conflicts with
+ definitions in conio.h.
+
+ All the file access functions have been renamed from the stdio syntax to
+ pack_fopen(), pack_getc(), etc, so they can now be mixed with stdio code.
+
+ Added pack_fgets() and pack_fputs().
+
+ The port_callback pointer no longer exists.
+
+ Removed polyline() (who ever used it?), and added a polygon(), which
+ draws a filled convex polygon with an arbitrary number of vertices.
+
+ Added do_line() and do_circle() functions, which call a user-supplied
+ function for each pixel that needs to be drawn.
+
+ Added a default keyboard interface to the GUI routines, allowing the
+ selection of objects with the arrow keys and <enter>.
+
+ Added several new GUI messages and flags. In particular there are now
+ messages for tracking mouse cursor movement, an idle message, a special
+ return value for the MSG_CHAR message which allows an object to override
+ the default keyboard handling, and a flag which hides the object.
+
+ There are new GUI routines to centre a dialog on the screen and to alter
+ the colors used by the standard alert and file selector dialogs.
+
+ The file selector now takes a third parameter specifying which file
+ extensions to display.
+
+ The timer routines now have better than millisecond accuracy, and it is
+ possible to alter the speed of a user timer callback in realtime (by
+ reinstalling it with a different speed value).
+
+ Removed the _RGB struct and paltorgb() functions. RGB's are now stored
+ directly in the hardware format, with each value in the range 0-63.
+
+ Added functions to get and set single palette entries as well as entire
+ palettes.
+
+ Added DPMI memory locking code.
+
+ Wrote a C++ 'fix' class which overloads a lot of operators, providing an
+ easy way to use the fixed point routines.
+
+ There are probably lots of other things that I have forgotten about.
+
+
+
+This is a short document about the introduction of `const'-correctness
+to Allegro. It details what changes have occurred to internal library
+code, the API changes (mainly transparent) and what you will need to do
+to adapt code to compile without warnings (again, mainly nothing).
+
+
+
+
+There are very few actual changes to the library code itself; only some
+symbol declarations and definitions have been altered to include
+AL_CONST. See below for a description of the AL_CONST preprocessor
+define. In a few places, some string was changed that should not have
+been - in these cases, the string is simply duplicated and then the
+duplicate is erased on exiting the function.
+
+
+In all, there were very few changes to the library code.
+
+
+
+
+In order to support compilers which don't know about the `const'
+keyword, or perhaps use a different keyword, the preprocessor symbol
+AL_CONST is used wherever `const' would normally be used. Note that in
+the documentation, I have used `const' for readability.
+
+
+
+
+These are, generally speaking, totally transparent to the user. I did
+not change the behaviour of any function; only its parameter types.
+Basically, if you can pass it as type* ptr, then you can
+pass it as const type* ptr without any problem whatsoever.
+Note also that certain changes may remove warnings in your program as
+static strings, etc, are now treated as `const' by Allegro functions.
+
+
+There are a few places, described below, where there will be an effect
+on existing code.
+
+
+`const'-correctness is deemed important for two reasons. Firstly, it can
+increase code readability and comprehension of Allegro functions (for
+instance, you can see which parameters are altered and which are not).
+Secondly, it ensures that the Allegro code is not changing data which it
+should not be, and that client callback functions are not breaking
+Allegro by changing data they should not be.
+
+
+
+
+Certain callback functions now have a different type - they take `const'
+pointers as opposed to non-`const' pointers. As far as I know, a
+compiler will issue a warning about incompatible pointer types. You
+should update your callback function to the new format (which will be
+listed in the main Allegro documentation).
+
+
+Also, when passing a pointer to a pointer to an Allegro function which
+is declared as taking an AL_CONST type** ptr, you will need
+to cast your pointer to be `const' if it is not already. For instance:
+
+I realise that this is a change to the Allegro API, and that we are
+supposed to avoid those at all costs, but this is essentially fixing a
+bug in Allegro and changing behaviour. It also ensures that
+client-supplied callback functions are functioning correctly, and not
+altering data that they should not. Callback functions which do not
+treat relevant parameters as `const' are, in a small (but potentially
+signficant) way, broken.
+
+
+Please note that for the Unicode function ugetx(), I have provided an
+alternative version ugetxc(), which takes a `const char**' parameter as
+opposed to a `char**' parameter. This is because it is valid to pass
+either a `char**' or a `const char**', but unfortunately there is no way
+to tell the compiler exactly what we mean.
+
+
+
+
+Allegro represents both a screen bitmap and a memory bitmap by a single
+object; a BITMAP. Unfortunately, these two things can be very different.
+For instance, reading a pixel from a bitmap would not seem to change it,
+but if it is a screen bitmap we are reading from, then it is possible
+that some parameter of the video card is changed to select the correct
+line, etc.
+
+
+Therefore, a const BITMAP parameter does not make sense, and is not used
+throughout the library. This is unfortunate, but I cannot see any way
+around it.
+
+
+
+
+Allegro `const'-correctness has been tested for quite enough time to say
+that it is working OK. However, if you still find problems with a compiler,
+please contact the Allegro mailing list; see `Contact info' in the Allegro
+documentation (readme.txt).
+
+
+As an alternative to the graphical grabber program, you can use the command
+line dat utility. This accepts the following options:
+
+
+ '-a <files>'
+
+
+ Adds the named files to the datafile, for example:
+
+
+ dat myfile.dat -a title.pcx scream.wav
+
+
+
+ If the objects are already present in the datafile, their current
+ contents will be replaced. Names for the new objects will be generated
+ from the input filenames, and the object type will be detected from
+ the file extensions. In some cases this is ambiguous, for example a
+ PCX file can be read as a bitmap, RLE sprite, compiled sprite, or font
+ object, so you may need to explicitly specify the object type with the
+ '-t' flag. For example, to insert alien.pcx as an RLE sprite, use the
+ command:
+
+
+ dat myfile.dat -a alien.pcx -t RLE
+
+
+
+ '-bpp colordepth'
+ Specifies which color format bitmap data should be grabbed in (valid
+ depths are 8, 15, 16, 24, and 32 bits per pixel).
+
+
+ '-c0' - no compression
+
+
+ '-c1' - compress objects individually
+
+
+ '-c2' - global compression on the entire datafile
+
+
+ Sets the compression mode (see below). These can be used on their own
+ to convert a datafile from one format to another, or in combination
+ with any other options.
+
+
+ '-d <objects>'
+
+
+ Deletes the named objects from the datafile.
+
+
+ '-dither'
+
+
+ Dithers graphics when reducing color depths.
+
+
+ '-e <objects>'
+
+
+ Extracts the named objects from the datafile. To extract everything,
+ use the wildcard * as the object name. To set the output filename or
+ directory, use the '-o filename' option. For example, to extract an
+ object called TITLE_SCREEN to the file title.pcx, use the command:
+
+
+ dat myfile.dat -e title_screen -o title.pcx
+
+
+
+ To extract the entire contents of the datafile to the directory
+ c:\output, use:
+
+
+ dat myfile.dat -e * -o c:\output\
+
+
+
+ '-f'
+
+
+ Stores the references to original files as relative filenames instead of
+ absolute filenames. This greatly increases the portability of complete
+ source trees containing the source data.
+
+
+ '-g x y w h'
+
+
+ Grabs bitmap data from a specific grid location.
+
+
+ '-h outputfile.h'
+
+
+ Sets the output header file, for exporting object index definitions.
+ This may be used on its own to produce a header file from an existing
+ datafile, or in combination with any other commands. You can also use
+ the '-p prefixstring' option to set a prefix string for the object
+ definitions.
+
+
+ '-k'
+
+
+ Keep original names while grabbing objects. Without this switch, a
+ file called image.pcx will be imported as an object called IMAGE_PCX,
+ to ensure that all the object names are valid symbols for the output
+ header defines.
+
+
+ '-l'
+
+
+ Lists the contents of the datafile. This can be combined with the '-v'
+ option to list object properties along with the names, and you can
+ specify particular objects to produce a partial listing.
+
+
+ '-m dependencyfile'
+
+
+ Writes a set of makefile dependencies into the specified file, which
+ can be used to automatically update the file whenever any of the
+ source data changes.
+
+
+ '-n0' - no sort: list the objects in the order they were added
+
+
+ '-n1' - sort the objects of the datafile alphabetically by name
+
+
+ Sets the sort mode (see below). These can be used on their own to
+ sort the objects of the datafile, or in combination with any other
+ options.
+
+
+ '-o output'
+
+
+ Sets the output file or directory when extracting data.
+
+
+ '-p prefixstring'
+
+
+ Sets the prefix for the output header file.
+
+
+ '-pal objectname'
+
+
+ Specifies which palette to use.
+
+
+ '-r'
+
+
+ Recursively adds directories as nested datafiles. This makes it possible
+ to maintain the data hierarchy within the datafile.
+
+
+ '-s0' - no strip: save everything
+
+
+ '-s1' - strip grabber specific information from the file
+
+
+ '-s2' - strip all object properties and names from the file
+
+
+ '-s-PROP' do not strip object property PROP from the file
+
+
+ Sets the strip mode (see below). These can be used on their own to
+ strip properties from the datafile, or in combination with any other
+ options.
+
+
+ '-t type'
+
+
+ Sets the object type when adding files.
+
+
+ '-transparency'
+
+
+ Preserves transparency when converting between color depths.
+
+
+ '-u'
+
+
+ Updates the contents of the datafile. See below.
+
+
+ '-v'
+
+
+ Selects verbose mode. This can be used in combination with any other
+ options to produce more detailed output.
+
+
+ '-w'
+
+
+ Always updates the entire contents of the datafile.
+
+
+ '-x <objects>'
+
+
+ Alias for '-e <objects>'.
+
+
+ '-007 password'
+
+
+ Sets the file encryption key.
+
+
+ '<objects> PROP=value'
+
+
+ Sets properties for the specified objects. This works like environment
+ variables, in that setting a property to an empty string removes it.
+ Because object names are stored as NAME properties, you can use this
+ command to rename objects. For example, to rename MY_OBJECT to
+ WHAT_A_SILLY_NAME, use the command:
+
+
+ dat myfile.dat my_object NAME=what_a_silly_name
+
+
+
+ You can use the wildcard * to apply the property to everything in the
+ file, so to remove the ORIG property from the entire datafile, you
+ could execute:
+
+
+ dat myfile.dat * ORIG=
+
+
+
+You can create hierarchical nested datafiles by inserting one datafile into
+another with the '-a' command. Objects in the nested datafile can then be
+referred to by as "parentname/objectname". For example if the datafile
+myfile.dat contains a nested datafile called nestedfile, which contains a
+bitmap called thepicture, you could export the bitmap with the command:
+
+
+ dat myfile.dat -e nestedfile/thepicture -o output.pcx
+
+The utility dat2c can be used in much the same way as dat2s, above, except
+that it writes C code rather than assembler. This has the advantage that it
+is portable - you can compile it anywhere you can use Allegro.
+
+
+
+
+Each option may appear only once. To specify which datafile to convert,
+give the filename without a preceding option.
+
+
+--cfile, -o
+ Arguments: filename
+
+
+ Gives the name of the C source file to output. Won't add a .c
+ extension, even if you don't specify one. By default, dat2c will
+ write to stdout.
+
+
+--hfile, -h
+ Arguments: filename
+
+
+ Gives the name of the C header file to output. Won't add a .h
+ extension, even if you don't specify one.
+
+
+--prefix, -p
+ Arguments: prefix (must be a valid macro name)
+
+
+ If you specify a prefix, then this will be used when constructing a
+ macro name for each object in the datafile. This is the same as the
+ grabber; if you don't specify a prefix, the macro name is simply
+ <obj_name>, but if you do, then the macro name becomes
+ <prefix>_<obj_name> .
+
+
+--crlf, -C
+ Arguments: none
+
+
+ Forces the file to be output in CRLF (DOS) format. This is the
+ default on DOS/Windows platforms.
+
+
+--unix, -U
+ Arguments: none
+
+
+ Sets the output to be in Unix (LF only) text format. This is the
+ default on non-DOS non-Mac platforms.
+
+
+--mac, -M
+ Arguments: none
+
+
+ Sets the output to be in Macintosh (CR only) text format. This is
+ the default on Mac platforms.
+
+
+--global, -g
+ Arguments: none
+
+
+ Specifies that the objects should be globally visible (default is
+ for objects to be local to the compilation unit). If they are
+ globally visible, then you can refer to them in your code.
+
+
+ (See note below for more info on compiled sprites). Tells dat2c to
+ convert any compiled sprite objects it finds into bitmap objects.
+ More a convenience feature for lazy people :-)
+
+
+--datafile-name, -n
+ Arguments: C identifier
+
+
+ By default, the datafile is exported as:
+ PREFIX_data
+ or data
+ But with this option, you can change 'data' to be something else.
+
+
+
+
+ - If your datafile contains truecolor images, be sure to call
+ fixup_datafile() after you have set the graphics mode. You must
+ also call fixup_datafile() if your platform does not support
+ constructors (currently any non GCC-based platform).
+
+
+ - Compiled sprites are *not* supported (but see the commandline option
+ --convert-compiled-sprites , above). This is because Allegro silently
+ switches to an RLE_SPRITE implementation on platforms which don't
+ support compiled sprites, and to get dat2c to implement that behaviour
+ would be more effort than it is worth (especially since you can just
+ call get_compiled_sprite() anyway!).
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/dat2s.html b/lib/allegro/allegro-htmldocs-4.2.1/dat2s.html
new file mode 100644
index 0000000..3b754e7
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/dat2s.html
@@ -0,0 +1,109 @@
+
+
+The utility dat2s can be used to convert a datafile into an asm (.s) source
+file, which can then be assembled and linked into your program. This avoids
+the need for a separate datafile to accompany your program, and means the
+data will automatically be loaded into memory at startup. You should be
+aware, though, that large datafiles can take a long time to compile, and
+that it is not possible to compress data which is compiled in this way.
+
+
+The simplest way to invoke dat2s is with the command:
+
+
+ dat2s filename.dat -o output.s
+
+
+The resulting asm file can then be assembled with the command:
+
+
+ gcc -c output.s
+
+
+This will produce an object module called output.o, which can be linked into
+your program, for example:
+
+
+ gcc myprog.c -o myprog.exe output.o -lalleg
+
+
+Your program can then access the contents of the datafile as simple global
+variables. Definitions for these variables can be obtained by telling dat2s
+to output a header file as well as the asm file, with the '-h' option. You
+can also use '-p' to set a prefix string for all the object names. For
+example, when applied to the datafile:
+
+
+Alternatively, you can use the datafile array for compatibility with code
+that was originally written for separately loaded datafiles, with the
+standard syntax item_data[index].dat.
+
+
+If your datafile contains truecolor images, be sure to call fixup_datafile()
+after you have set the graphics mode. You must also call fixup_datafile()
+if your platform does not support constructors (currently any non GCC-based
+platform).
+
+
+Note that compiled sprites are not supported and will cause dat2s to
+abort whenever it encounters one of them. However you can use the '-S'
+option to instruct dat2s to convert them to regular BITMAP objects.
+
+
+Note that datafiles compiled by dat2s must not be appended to shared objects,
+only to standalone executables. Use dat2c for this purpose.
+
+
+
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/datafile.html b/lib/allegro/allegro-htmldocs-4.2.1/datafile.html
new file mode 100644
index 0000000..ef44d5d
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/datafile.html
@@ -0,0 +1,333 @@
+
+
+An Allegro datafile is a bit like a zip file in that it consists of lots of
+different pieces of data stuck together one after another, and optionally
+compressed. This means that your game doesn't have to clutter up the disk
+with hundreds of tiny files, and it makes programming easier because you can
+load everything with a single function call at program startup. Another
+benefit is that the LZSS file compression algorithm works much better with
+one large file than with many small ones.
+
+
+Datafiles have the extension .dat, and can be created and edited with the
+graphical grabber program or the command line dat utility. They can be
+stored as separate files and loaded into memory by the load_datafile()
+function, or you can use dat2s to convert them into asm code which can then
+be linked directly into your executable.
+
+
+Each datafile contains a number of objects, of varying types. Object types
+are represented by 32 bit integer ID's, which are interpreted as four
+character ASCII strings. These ID's can be constructed with the DAT_ID()
+macro, for example a DATA object is represented by DAT_ID('D','A','T','A'),
+or you can use the predefined DAT_* constants for the standard data types:
+
+
+
+DAT_FILE - "FILE"
+ A datafile, which contains a list of other objects. Datafile objects
+ can be nested inside other datafiles, allowing you to create
+ hierarchical structures of any depth.
+
+
DAT_DATA - "DATA"
+ A block of binary data. Allegro treats all unknown types as binary
+ data objects, so you don't need to use this ID: you can create custom
+ object formats using whatever ID's you like.
+
+
DAT_RLE_SPRITE - "RLE "
+ A run length encoded sprite.
+
+
DAT_C_SPRITE - "CMP "
+ A compiled sprite.
+
+
DAT_XC_SPRITE - "XCMP"
+ A mode-X compiled sprite.
+
+
DAT_PALETTE - "PAL "
+ A 256 color palette.
+
+
DAT_PROPERTY - "prop"
+ An object property (see below). You will never directly encounter this
+ object type, but you should be aware that it is treated specially by
+ the datafile code.
+
+
DAT_INFO - "info"
+ The grabber utility uses this object to store information about the
+ datafile. Like property objects, you ought never to encounter it, but
+ you should avoid using the ID for any custom object formats you create.
+
+
DAT_END - -1
+ Special marker used to indicate the end of a datafile.
+
+Each object can have any number of properties attached to it. These are
+ASCII strings describing attributes of the object, such as its name and
+where it came from. Like the objects themselves, properties are identified
+by 32 bit integer ID's which are constructed from four character strings by
+the DAT_ID() macro. Allegro defines the standard properties:
+
+
+
+"NAME"
+ The name of the object.
+
+"ORIG"
+ The object's origin, ie. the name of the file from which it was
+ grabbed.
+
+"DATE"
+ A timestamp, used by the update command in the grabber and dat
+ utilities. This is the modification time of the file from which the
+ object was grabbed, in "m-dd-yyyy, hh:mm" format.
+
+"XPOS"
+ For bitmap objects which were grabbed from part of a larger image, the
+ x position of the origin within the parent bitmap.
+
+"YPOS"
+ For bitmap objects which were grabbed from part of a larger image, the
+ y position of the origin within the parent bitmap.
+
+"XSIZ"
+ For bitmap objects which were grabbed from part of a larger image, the
+ width of the selected region.
+
+"YSIZ"
+ For bitmap objects which were grabbed from part of a larger image, the
+ height of the selected region.
+
+"XCRP"
+ For autocropped bitmap objects, the amount of cropping on the left of
+ the image.
+
+"YCRP"
+ For autocropped bitmap objects, the amount of cropping at the top of
+ the image.
+
+
+
+You can use whatever other ID's you like to store custom information about
+your objects (the grabber internally use some other properties stored in a
+hidden DAT_INFO object, so they won't conflict with yours).
+
+
+
+
+In case anyone wants to do some serious hackery, and for my own future
+reference, here are some details of the innards of the datafile format.
+
+
+Note that this is different to the datafile format used by Allegro versions
+2.1 and earlier. Allegro can still load files from the old format, but it
+was much less flexible and didn't support nice things like object
+properties, so you should load any old files into the grabber and save them
+out again to convert to the new format.
+
+
+Nb. if all you want to do is write a utility that manipulates datafiles in
+some way, the easiest approach is probably to use the helper functions in
+datedit.c, which are currently shared by the dat, dat2s, and grabber
+programs. These functions handle loading, saving, inserting and deleting
+objects, and modifying the contents of datafiles in various ways, but life
+is too short for me to bother documenting them all here. Look at the
+source...
+
+
+Anyway. All numbers are stored in big-endian (Motorola) format. All text is
+stored in UTF-8 encoding. A datafile begins with one of the 32 bit values
+F_PACK_MAGIC or F_NOPACK_MAGIC, which are defined in allegro.h. If it starts
+with F_PACK_MAGIC the rest of the file is compressed with the LZSS
+algorithm, otherwise it is uncompressed. This magic number and optional
+decompression can be handled automatically by using the packfile functions
+and opening the file in F_READ_PACKED mode. After this comes the 32 bit
+value DAT_MAGIC, followed by the number of objects in the root datafile (not
+including objects nested inside child datafiles), followed by each of those
+objects in turn.
+
+
+Each object is in the format:
+
+
+ OBJECT =
+ var - <property list> - any properties relating to the object
+ 32 bit - <type ID> - object type ID
+ 32 bit - <compressed size> - size of the raw data in the file
+ 32 bit - <uncompressed size> - see below
+ var - <data> - the contents of the object
+
+
+
+The property list can contain zero or more object properties, in the form:
+
+
+ PROPERTY =
+ 32 bit - <magic> - "prop"
+ 32 bit - <type ID> - property type ID
+ 32 bit - <size> - size of the property string, in bytes
+ var - <data> - property string, _not_ null-terminated
+
+
+
+If the uncompressed size field in an object is positive, the contents of the
+object are not compressed (ie. the raw and compressed sizes should be the
+same). If the uncompressed size is negative, the object is LZSS compressed,
+and will expand into -<uncompressed size> bytes of data. The easiest way to
+handle this is to use the pack_fopen_chunk() function to read both the raw
+and compressed sizes and the contents of the object.
+
+
+The contents of an object vary depending on the type. Allegro defines the
+standard types:
+
+
+ DAT_FILE =
+ 32 bit - <object count> - number of objects in the sub-file
+ var - <object list> - objects in the same format as above
+
+ DAT_FONT =
+ 16 bit - <font size> - 8, 16, -1, or 0
+
+ if font size == 8 { - obsolete as of version 3.9.x!
+ unsigned char[95][8] - 8x8 bit-packed font data
+ }
+
+ if font size == 16 { - obsolete as of version 3.9.x!
+ unsigned char[95][16] - 8x16 bit-packed font data
+ }
+
+ if font size == -1 { - obsolete as of version 3.9.x!
+ 95x {
+ 16 bit - <width> - character width
+ 16 bit - <height> - character height
+ var - <data> - character data (8 bit pixels)
+ }
+ }
+
+ if font size == 0 { - new format introduced in version 3.9.x
+ 16 bit - <ranges> - number of character ranges
+ for each range {
+ 8 bit - <mono> - 1 or 8 bit format flag
+ 32 bit - <start> - first character in range
+ 32 bit - <end> - last character in range (inclusive)
+ for each character {
+ 16 bit - <width> - character width
+ 16 bit - <height> - character height
+ var - <data> - character data
+ }
+ }
+ }
+
+ DAT_SAMP =
+ 16 bit - <bits> - sample bits (negative for stereo)
+ 16 bit - <freq> - sample frequency
+ 32 bit - <length> - sample length
+ var - <data> - sample data
+
+ DAT_MIDI =
+ 16 bit - <divisions> - MIDI beat divisions
+ 32x {
+ 32 bit - <length> - track length, in bytes
+ var - <data> - MIDI track data
+ }
+
+ DAT_FLI =
+ var - <data> - FLI or FLC animation, standard format
+
+ DAT_BITMAP =
+ DAT_C_SPRITE =
+ DAT_XC_SPRITE =
+ 16 bit - <bits> - bitmap color depth
+ 16 bit - <width> - bitmap width
+ 16 bit - <height> - bitmap height
+ var - <data> - bitmap data
+
+ Valid color depths are 8, 15, 16, 24, 32, and -32. Both 15 and 16 bit
+ images are stored in 5.6.5 RGB format, and 24 and 32 bit images as
+ 8.8.8 RGB. The special -32 flag indicates that the data is in true 32
+ bit RGBA format.
+
+ DAT_RLE_SPRITE =
+ 16 bit - <bits> - sprite color depth
+ 16 bit - <width> - sprite width
+ 16 bit - <height> - sprite height
+ 32 bit - <size> - data size, in bytes
+ var - <data> - RLE compressed sprite data
+
+ Valid color depths are 8, 15, 16, 24, 32. and -32. Both 15 and 16 bit
+ images are stored in 5.6.5 RGB format with 16 bit skip counts and EOL
+ markers, and 24 and 32 bit images as 8.8.8 RGB. with 32 bit skip
+ counts and markers. The special -32 flag indicates that the data is in
+ true 32 bit RGBA format.
+
+ DAT_PALETTE =
+ 256 x {
+ 8 bit - <red> - red component, 0-63
+ 8 bit - <green> - green component, 0-63
+ 8 bit - <blue> - blue component, 0-63
+ 8 bit - <pad> - alignment padding
+ }
+
+
+
+I think that covers everything.
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/faq.html b/lib/allegro/allegro-htmldocs-4.2.1/faq.html
new file mode 100644
index 0000000..149ec9d
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/faq.html
@@ -0,0 +1,1077 @@
+
+
+Allegro FAQ
+
+
+
+
+
+The Allegro FAQ
+If the answer isn't here, ask and it will be added...
+ The Allegro licence is absolutely clear unless you are a lawyer.
+ However, it's written quite informally so this mini-FAQ tries to clarify
+ some things.
+
+
+ No. Every Allegro contributor holds the copyright for the code he or
+ she wrote. This means he or she grants you the right to use it for
+ any purpose you want. But the fact that the contributor holds the
+ copyright means that you e.g. cannot claim that you wrote the code.
+
+
+ See the previous question. Since Allegro is compatible with about any
+ license, it also is OSI compatible. It clearly is compatible with all the
+ points in the OSD (open source definition). You can search the OSI
+ mailing list for "Allegro" to see that OSI shares this view. (OSI
+ officials still were reluctant to consider it for approval though and
+ suggested to use an existing license like MIT instead.)
+
+
+ You can modify Allegro and distribute the modified Allegro under
+ any licence you want, but the original unmodified parts will still
+ be licenced under the Allegro licence. If you offer your
+ modifications to be included in the official Allegro distribution
+ (e.g. by sending them to the Allegro developers mailing list) you
+ automatically agree with licencing the modification under the
+ Allegro licence.
+
+
+ We are programmers not lawyers. This FAQ represents our current
+ understanding of copyright law (or copyright laws in different
+ countries). But given the license, which allows everything, and
+ the disclaimer, which says we take no responsibility for anything,
+ we really don't see how there could be any problems.
+
+ Make is part of the standard djgpp distribution, in the file
+ v2gnu/mak*b.zip (whatever the latest version number is).
+ You can get this from http://www.delorie.com/djgpp/.
+
+
+
+ Are you sure that you have installed djgpp correctly? Check the
+ instructions in the djgpp readme.1st file, and in particular confirm
+ that you have set the DJGPP environment variable and added the
+ djgpp\bin directory to your path.
+
+
+
+ Are you sure that you are using the GNU make program, and not some
+ other version like the Borland one? If in doubt, run make -v and
+ check that the GNU copyright message is displayed.
+
+
+
+ You shouldn't be running make from the Win95 explorer! Bring up a DOS
+ box, change to your Allegro directory, and type make at the command
+ prompt.
+
+
+
+ Are you sure that your system time and date are set correctly?
+ Alternatively you may have downloaded a fresh file made by someone in a
+ more eastern timezone. In the latter case you can either wait a few
+ hours, temporarily set your clock forward, or use a utility such as
+ touch to change the timestamp of the files.
+
+
+
+ As the error message suggests, you need to provide more memory for the
+ compiler to use. The go32-v2 program will tell you how much is
+ currently available. If you are running under DOS, try to free up more
+ disk space for use as a swapfile. When using win95, increase the DPMI
+ memory limit in the properties for your DOS session to 65535 (you'll
+ have to type this in by hand, because the pulldown list doesn't go
+ above 16384).
+
+
+
+ As the error message suggests, there is a conflict between newer
+ versions of gcc and older versions of the libc. You must upgrade your
+ djdevxxx.zip package to the latest update (timestamp 11 August 2002)
+ of DJGPP-2.03 or above.
+
+
+
+ C:\TEMP\ccdaaaaa(.text+0x9):x.c: undefined reference to `allegro_init'
+ C:\TEMP\ccdaaaaa(.text+0xe):x.c: undefined reference to `install_keyboard'
+
+
+ You haven't read the docs, have you? :-) You need to link your program
+ with the library file, liballeg.a. First, make sure you have installed
+ everything properly (running make install should do this for you).
+ Second, if you are compiling from the command prompt or with a makefile,
+ add -lalleg to the end of your gcc command line, or if you are using Rhide,
+ go to the Options/Libraries menu, type alleg into the first empty field,
+ and make sure the box next to it is checked.
+
+
+
+ No, sorry. For starters, liballeg.a is about 450k, but you'd probably
+ also want various utilities like the grabber, sound setup, etc. And
+ what about all the example programs? If we included compiled versions
+ of everything, a binary distribution would be over 7 megs: way too big
+ to be practical! More seriously though, there just isn't any reason
+ why you can't build it yourself. A compiler is a deterministic
+ process: given a particular input file and command line, it will always
+ produce the same output. If this isn't working, you either have the
+ wrong input files (ie. your copy of Allegro is broken in some way), or
+ the wrong command line (it is hard to see how that could happen, since
+ all you have to do is type make...) or your compiler is broken, ie. you
+ didn't install djgpp properly. You need to find and fix the problem,
+ not just sweep it under the carpet by getting someone else to compile
+ Allegro for you...
+
+
+
+ GNU tools write their error messages to the error stream, stderr.
+ Unfortunately command.com is too stupid to know how to redirect this,
+ but fortunately DJ was smart enough to work around that, so you can
+ use his redir program to capture the output messages, for example
+
+ Your mileage may vary. Some people have reported problems, while
+ others say that it works fine. Use the Windows version of Allegro
+ if you want to make Windows programs. If you want to run DOS
+ programs, use DOS!
+
+
+
+ Yes, but with some caveats. If you are using the OpenDOS version of
+ EMM386, you must disable their DPMI implementation (specify DPMI=OFF
+ on the EMM386.EXE device line in your config.sys). You should also
+ make sure the PIC=OFF flag is set, but this is the default so it won't
+ be a problem unless you have specifically enabled it.
+
+
+
+ You can't. The limit is imposed by the VGA hardware, not by Allegro.
+ To access more than 256k of video memory you need to use an SVGA mode,
+ which means either switching to a higher resolution or getting a copy
+ of the SciTech Display Doctor, which provides several low resolution
+ SVGA modes.
+
+
+
+ It does for some people, but not for others. The problem is that
+ Creative Labs refuse to release any specs, so we don't know how to
+ write a driver for it. Complain to them, or buy a different card from
+ a more reasonable manufacturer.
+
+
+
+ This might be because you have the volume set very low: try changing
+ this in the setup program. Also, Allegro is mixing several sounds into
+ a single output buffer, unlike the Windows sound player that only
+ plays one sample at a time, so each individual sound can only get a
+ smaller percentage of the total output volume. This is just the price
+ you pay for multiple output channels. If you don't like it, use the
+ setup program to tweak the number of channels: this can be any power
+ of two less than or equal to 64, and the smaller you make it, the
+ louder the sound will be. Alternatively, use set_volume_per_voice(),
+ described in the docs. This will enable you to adjust the overall
+ volume of Allegro's digital sound output.
+
+
+
+ Try using a FreeBE/AF driver (http://www.talula.demon.co.uk/freebe/),
+ or the commercial SciTech Display Doctor (http://www.scitechsoft.com).
+ If it still doesn't work, post a description of your problem to the
+ Allegro mailing list, along with a copy of the output from running the
+ afinfo and vesainfo programs.
+
+
+
+ The VBE/AF interface already provides this for the video drivers: see
+ the FreeBE/AF project on http://www.talula.demon.co.uk/freebe/.
+ For more general things like the sound, VESA, and mode-X routines,
+ this would be very difficult to do because the drivers depend on a lot
+ of helper functions from the core lib. The djgpp DXE format is nowhere
+ near flexible enough to support this, and we don't want to make Allegro
+ dependent on any other dynamic linking packages.
+
+
+
+ Well duh, you need to increase the size of your environment then :-)
+ You can do this by changing the settings for your DOS box (click the
+ system menu and select "properties"), or at startup in your config.sys
+ file (eg. shell=c:\command.com /e:8192 /p).
+
+ Well duh, you need to increase the size of your environment then :-)
+ You can do this by changing the settings for your DOS box (click the
+ system menu and select "properties"), or at startup in your config.sys
+ file (eg. shell=c:\command.com /e:8192 /p).
+
+
+
+ Make sure that you don't have a semi-colon appended to your MSVCDIR
+ variable if you are using MSVC, to your MINGDIR variable if you are
+ using MinGW or to your BCC32DIR variable if you are using BCC.
+ Also run make -v from the command line and make sure you are using
+ GNU make and not Borland make or Microsoft make.
+
+
+
+ You need to tell your compiler how to find the DirectX include files
+ and libraries: put the DirectX SDK /include and /lib directories in the
+ compiler/linker path. Alternatively, if you don't want to modify any
+ configuration stuff, you can simply copy the files from the DirectX SDK
+ /include and /lib directories to the corresponding ones for your
+ compiler.
+
+
+
+ You need to write END_OF_MAIN() just after your main() function.
+ Allegro uses this, along with some preprocessor magic, to turn a normal
+ main() function into a Windows-style WinMain() entry point.
+
+
+
+ Make sure you're building a Windows GUI Application, and not a Windows
+ Console Application. This is a setting when you create the project in
+ MSVC, Dev-C++ or Borland C++ Builder. Alternatively, this is specified
+ on the command line by the -subsystem:windows option for the MSVC
+ linker, by the -Wl,--subsystem,windows option for the MinGW compiler
+ or the -tW option for the Borland C++ compiler. Either that, or define
+ the preprocessor symbol ALLEGRO_USE_CONSOLE prior to including Allegro
+ headers if you really need the console for your program.
+
+
+
+ If your program directly includes Win32 API header files, see the
+ "Windows specifics" section of the documentation.
+
+
+ If your program only includes header files of the C++ standard library,
+ you're very likely trying to compile it with gcc 3.x for MinGW; if so,
+ define the symbol __GTHREAD_HIDE_WIN32API on the compiler command line:
+
+ Disable direct updating for the DirectX windowed driver by using the
+ dedicated configuration variable. See the 'Configuration routines'
+ section in the docs and the allegro.cfg template file for more
+ detailed informations.
+
+
+
+ Disable direct updating for the DirectX windowed driver by using the
+ dedicated configuration variable. See the 'Configuration routines'
+ section in the docs and the allegro.cfg template file for more
+ detailed informations.
+
+ You need to write END_OF_MAIN() just after your main() function.
+ Allegro uses this, along with some preprocessor magic, to get a copy
+ of your argv[] parameters (it needs those for various internal things).
+
+
+
+ You are probably on a Darwin/MacOS X system. If so, make sure the symbol
+ USE_CONSOLE is not defined in your program: it is a deprecated symbol
+ that must be replaced by ALLEGRO_USE_CONSOLE. Also note that the magic
+ main can't be disabled on such a system: you simply can't define the
+ symbol ALLEGRO_NO_MAGIC_MAIN in a program linked against Allegro.
+
+
+
+ You need to redirect stderr into a file, so you can view them later.
+ The method for doing this depends on your shell: if you are using a
+ Bourne-style shell like bash, try make 2> logfile.txt
+
+
+
+ You need to teach the dynamic linker where to find the Allegro shared library.
+ See docs/build/unix.txt, near the end of the 'Installing Allegro' section.
+
+
+
+ There are two possible reasons:
+ 1) DGA2 may support different resolutions/color depths than X,
+ run the gfxinfo program to know what combinations you can use,
+ 2) You may have a buggy DGA2 implementation, see next question.
+
+
+
+ You are probably using a XFree86 server with a very buggy DGA2
+ implementation, such as 4.0.3 (shipped with Red Hat 7.1 for example).
+ Upgrading to 4.1.0 will probably solve your problem. You can obtain
+ it from ftp://ftp.xfree86.org/pub/XFree86/4.1.0/binaries/ selecting
+ the directory suited to your platform and following the instructions
+ you find in the Install file.
+
+ The grabber needs to be linked with the code in datedit.c. But you
+ shouldn't have to worry about doing this by hand: just run make and
+ that will build everything for you.
+
+
+
+ Not unless <foobar> is mentioned in readme.txt as one of the
+ supported platforms. You could port it, but that is usually a lot of
+ work. If <foobar> is a 16 bit DOS compiler like Borland C, you
+ might as well just forget the idea :-)
+
+
+
+ WIP stands for "work in progress", and refers to any changes that are
+ more recent than the last official release. WIP versions of the
+ library can be obtained as patches from the Allegro website
+ (http://alleg.sourceforge.net/), and are usually
+ quite stable, although obviously not so well tested as a final release
+ version.
+
+
+
+ Do you have a copy of patch.exe? If not, go and get it from the same
+ place that you downloaded the rest of djgpp: this tool is a standard
+ part of the compiler distribution. Similarly, you can get the Mingw
+ compiled version from http://sourceforge.net/projects/gnuwin32/.
+
+
+ If you do have the patch program but it isn't working properly, make
+ sure that you are installing the patch over the top of an unmodified
+ copy of whatever Allegro version it is intended to update (this will
+ usually be the most recent official release from before the WIP was
+ made, but check the text file that comes with the WIP to be sure).
+
+
+
+ This is just the way that the video hardware works: there can only be
+ one palette in use at any given moment. Either convert your images so
+ they all use the same palette, or switch to a truecolor graphics mode.
+
+
+
+ The VGA hardware only uses 6 bits for each color component, which
+ means the red, green, and blue values in the palette structure range
+ from 0 to 63, not all the way up to 255. That gives you a potential
+ 2^18 = 262144 different colors, or 64 shades of grey. If you need more
+ than this you could try using VESA function 0x4F08 to select an 8 bit
+ wide DAC, but Allegro doesn't support this directly and I don't know
+ how reliable it will be across different hardware.
+
+
+
+ When you are in a 256 color mode, the VGA card displays color #0
+ around the border of the display area (in truecolor modes it displays
+ black). Your funny color will go away if you change the palette so
+ that color #0 is black.
+
+
+
+ With great difficulty :-) There is no such easy trick as just altering
+ the palette, so you will have to repeatedly redraw the image in a
+ lighter or darker form. You could draw black translucent rectangles
+ over the screen to darken it down, or use draw_lit_sprite() to tint a
+ bitmap while copying it to the screen, but be warned that these
+ operations are expensive and will require a fast PC!
+
+
+ Also, have a look at http://www.allegro.cc/ for add-on packages
+ (notably FBlend v0.5) that attempt to make this operation as fast as
+ possible.
+
+
+
+ See the Allegro.cc homepage (http://www.allegro.cc/)
+ for some utilities, for example DTA and Smacker. Also, you can use ASE
+ (Allegro Sprite Editor, http://ase.sourceforge.net/), which allows
+ drawing/editing each frame of the animation and save it as a FLI. Or
+ you can use The GIMP (http://www.gimp.org/) along with it's GFli
+ plugin, using layers as frames, and saving your work as file.fli.
+ The GIMP allows you to edit existent FLI files too.
+
+
+
+ In your favourite paint program, get hold of the RGB sliders and drag
+ the red and blue ones up as far as they go (usually to 255, but this
+ will depend on what units your software uses), and the green one right
+ down to zero. The result is a special shade of Magic Pink, or as some
+ people prefer to call it, magenta.
+
+
+
+ Remember that the vertex positions are stored in fixed point format,
+ so you must use the itofix() macro or shift your coordinates 16 bits
+ to the left.
+
+
+
+ Remember that the angle of rotation is stored in fixed point format,
+ so you must use the itofix() macro or shift your coordinates 16 bits
+ to the left. For example, rotate_sprite(bmp, spr, x, y, itofix(32))
+ will rotate the graphic by 45 degrees.
+
+
+
+ You are probably trying to initialise the dialog structure with a
+ pointer to your bitmap, right? That won't work because the dialog is
+ created at compile time, but the bitmap is only loaded at runtime, so
+ the compiler doesn't yet know where it will be located. You need to
+ fill in the dialog structure with a NULL pointer, and then copy the
+ real bitmap pointer into the dp field as part of your program init
+ code, after you've loaded the bitmap into memory.
+
+
+
+ It depends on exactly what you are doing. If your images are totally
+ opaque, there is no advantage to using an RLE sprite, and it will
+ probably be faster to use a regular bitmap with the blit() function.
+ If your graphics contain masked areas, an RLE sprite may be both smaller
+ and faster than the draw_sprite() function, depending on your CPU
+ and your bitmaps.
+ Compiled sprites are in general quite a bit faster than both the
+ others for masked images, and slightly faster for opaque graphics, but
+ this is far more variable. They are at their best with small sprites,
+ on older machines and in mode-X, and may actually be slower than
+ blit() when using SVGA modes on a pentium (the large size of a
+ compiled sprite is very bad for the cache performance).
+
+
+
+ You need to make sure the game logic gets updated at a regular rate,
+ but skip the screen refresh every now and then if the computer is too
+ slow to keep up. This can be done by installing a timer handler that
+ will increment a global variable at your game logic speed, eg:
+
+ Add a call to save_bitmap() somewhere in your code. See the
+ save_bitmap() documentation for a discussion of one common pitfall
+ when doing this, and some example code.
+
+
+
+ There is no need. The linker will only include the parts of the
+ library that you actually use, so if you don't call any of, say, the
+ texture mapping or FLIC playing functions, they will be left out of
+ your executable. This doesn't work perfectly because a lot of the
+ Allegro code uses tables of function pointers that cause some
+ unnecessary routines to be linked in, so the majority of the graphics
+ functions will be included in every executable, but I have tried to
+ keep this to a minimum. See allegro.txt for information about more
+ precise ways to remove some of the graphics and sound drivers.
+
+
+
+ No. This sort of hardware support would be most useful as part of a
+ proper 3D API, which Allegro is not, and will never be. If you want
+ to do some work on this, the MESA library (a free implementation
+ of OpenGL) is IMHO the place to start.
+
+
+ However, if you are interested in using OpenGL for graphics and Allegro
+ for everything else, you can try the various add-ons libraries linked
+ from http://www.allegro.cc/ such as AllegroGL.
+
+
+
+ Several very good ones already exist, for instance the JGMOD or DUMB
+ packages. See the audio library extensions section on the Allegro.cc
+ website (http://www.allegro.cc/). You are not allowed to suggest
+ that one of these libraries be merged into Allegro, because this topic
+ has already been done to death on the mailing list and we are tired of it.
+
+
+
+ There are several networking packages currently in development or
+ floating around on the net, though, and in our opinion this sort of
+ code is more useful as an external library than it would be as part of
+ Allegro.
+
+
+
+ Unisys has a patent on the LZW compression algorithm that is used by
+ the GIF format. We want everything in Allegro to be freely usable
+ without any restrictions whatsoever, which means we can't include any
+ code that is subject to licensing or the payment of royalties.
+
+
+
+ Perhaps. Try to isolate the smallest fragment of code that is able to
+ reproduce the problem, and we'll have a look at it. If you can send us
+ a 10 line program, we will fix it. 100 lines, and we can probably fix
+ it. 1000 lines, and we don't have a chance :-)
+
+
+
+ Whenever it is done! A little encouragement is always welcome, but we
+ don't have any completion deadlines and we're not going to make one up
+ for you :-) As soon as it is finished, it will be released.
+
+
+
+ The grabber can import directly from GRX or BIOS format .fnt files, or
+ you can draw them onto a .pcx image using any paint program. See
+ http://www.talula.demon.co.uk/ttf2pcx/ for a utility that
+ will convert Windows TrueType fonts into this .pcx format.
+
+
+
+ See the Allegro homepage (http://alleg.sourceforge.net/)
+ for some links. You can use Gravis patches (.pat format), or SoundFont
+ 2.0 (.sf2) files, but the latter must be converted into a patches.dat
+ file with the pat2dat utility.
+
+
+
+ You need to download the makertf conversion utility
+ (ftp://ftp.coast.net/Coast/win3/winhelp/mkrtf104.zip), and the Windows
+ Help compiler (ftp://ftp.microsoft.com/Softlib/MSLFILES/HC505.EXE).
+ Make a temporary directory, copy the allegro.txi file from the
+ allegro/docs dir, and run the commands makertf --no-warn allegro.txi
+ -o allegro.rtf -J allegro.hpj followed by hcp allegro.hpj. The
+ second command will give a lot of warnings, but they can safely be
+ ignored.
+
+
+
+ The allegro.rtf file can be read directly into Microsoft Word and
+ printed from there, but you should right-click and update the table of
+ contents and index fields to fill them with the correct data first.
+ Alternatively you can install the TeX package and use the tex and
+ dvips programs to convert allegro.txi into Postscript format.
+
+
+
+ It simplifies the maintenance of your program, in case the value of PI
+ ever needs to be changed. Also it will make your program more portable
+ to other compilers that use different values of PI.
+
+
+
+ A number of graphics cards have buggy or incomplete VESA
+ implementations, and often the vsync() function is not implemented. For
+ examples on flicker-free drawing, look at the code for the demo game,
+ which uses a variety of methods to draw itself.
+
+
+
+Various options can be set using the buttons and text fields at the top of
+the screen. You can edit the name of the datafile, the name of the header
+file for exporting object indexes (leave this blank if you don't want to
+output a header), and the prefix string for the header file definitions. You
+can change the grid settings for grabbing bitmaps, and alter the compression
+mode (see below). You can enable or disable backups: if this box is checked,
+the old version will be renamed to a .bak extension when datafiles are saved.
+You can also turn dithering on (this can improve the image quality when you
+reduce graphics from 15, 16, 24 or 32-bit color to 8-bit color and from 24 or
+32-bit color to 15 or 16-bit color) and enable transparency preserving (this
+will ensure that the masked areas in bitmaps stay exactly the same through
+color conversion).
+
+
+The contents of the datafile are listed in the box at the bottom left of the
+screen, and can be selected with the mouse or arrow keys. Multiple objects
+can be selected by holding down the shift or control keys while you click
+on the list or move the cursor. The selected object can be edited with
+commands from the Object menu, or using the shortcut menu produced by
+pressing Esc or right-clicking on an object. Double-clicking on an object
+performs a function which varies depending on the type of the object.
+Bitmaps are displayed full-screen (use the plus and minus keys to zoom in
+and out), samples and MIDI files are played, palettes are selected (meaning
+that they will be used when displaying and exporting bitmaps), and fonts can
+be edited by adding and removing specific character ranges.
+
+
+
+
+New objects can be created using the menus or by pressing Insert while the
+item list has the input focus. To make nested datafiles, create a FILE
+object (New/Datafile), and select it before inserting other objects.
+
+
+To insert information into a datafile you must first create an object of the
+appropriate type, and then select the grab command (keyboard shortcut
+ctrl+G). For most objects this will bring up a file selector for you to
+select the file to read, but for graphic objects (bitmaps, RLE sprites,
+compiled sprites, and palettes) it will grab from the current contents of
+the image buffer, so you must previously have read a picture into this
+buffer with the File/Read Bitmap command (keyboard shortcut ctrl+G). You can
+use the mouse or arrow keys to select which portion of the image to grab.
+With the mouse, select the top left corner, click and hold the left mouse
+button, and move to the bottom right corner before releasing the button.
+Press the right mouse button to cancel. With the keyboard, use the arrow
+keys to select the top left corner, press Space or Enter, adjust the size
+with the arrow keys, and press Space or Enter again. By default the position
+will snap to a 16x16 grid, which can be adjusted by changing the values in
+the X-grid and Y-grid fields. Alternatively you can use the Box Grab
+command, in which case you should draw a bounding box in color #255 around
+your sprites, and can then just click once inside a box to grab the contents.
+
+
+Note that palette data is not stored along with bitmap and sprite objects.
+To store the entire contents of a PCX or BMP file, you will need to create
+both bitmap and palette objects, and grab data into both of them. When you
+reload the datafile the bitmap will probably be displayed with the wrong
+palette. This can be corrected by double-clicking on the palette object,
+which will select its contents as the current palette, meaning that it will
+be used when displaying and exporting bitmaps.
+
+
+The properties of the selected object are listed in the box to the right of
+the item list. These can be edited by double-clicking on one of the
+properties, and deleted by selecting one and pressing Del. You can insert
+new properties by pressing Insert while the property list has the input
+focus, or using the Object/Set Property command. Object names are stored as
+NAME properties, so the rename command is simply a shortcut for editing this
+property.
+
+
+
+
+To simplify the process of grabbing several related images from a single
+bitmap (for example a set of frames which form an animation), you can use
+the File/Grab from Grid command. Like the normal bitmap grab command, this
+uses data from the image buffer, so you must read in a bitmap before you use
+it. You will then be able to adjust the grabbing parameters, enter a name
+for the new objects, and choose the type of object to create (bitmap, RLE
+sprite, or compiled sprite). Because several objects may be created, their
+names will be formed by adding a number to the end of the name you supply,
+for example if you enter "a_picture", the grabber will create the objects
+"a_picture000", "a_picture001", etc. There are two grabbing modes: using
+cutouts of color 255, and using a regular grid. The regular grid option
+simply divides the bitmap up into a set of equally sized tiles, using the
+specified grid size, and grabs each of these as a separate object. If you
+set the Skip Empties flag, the grabber will ignore tiles that don't contain
+any data (ie. those that are a single solid color). The color 255 option is
+more flexible. It expects the bitmap to contain information describing the
+position and size of each tile, in the form of a bounding box drawn in color
+255. The most reliable way to do this is to fill all the image except the
+parts you want with color 255, but the grabber should be able to understand
+more complicated layouts, even if you simply draw color 255 lines along the
+top and left edges of the area you want to be grabbed. For truecolor images
+where color 255 is not particularly meaningful, use a cyan bounding box
+(maximum blue and green, zero red), with a single yellow (maximum red and
+green, zero blue) pixel in the top left corner of the box.
+
+
+
+
+By default, the grabber will run in a 640x480 resolution, using the highest
+color depth possible on your graphics card. If you want to override this,
+you can specify an alternative color depth or resolution on the commandline,
+eg. "grabber -8" for a 256 color mode, "grabber -16" for 16 bit hicolor
+graphics, "grabber -320x200" to use VGA mode 13h, or "grabber 1024x768".
+Warning: editing datafiles that contain truecolor graphics is very slow in
+256 color video modes, and the grabber is not really usable in resolutions
+lower than 640x400.
+
+
+You can configure the grabber to use external tools for editing data, by
+setting some variables in the [grabber] section of the allegro.cfg file.
+These are in the form "type=command", where the type is a four letter object
+ID, and the command is whatever program you want to be invoked to edit this
+kind of data. For these variables to be seen, the allegro.cfg file must
+either be in the same directory as the grabber executable, or in the
+directory pointed to by your ALLEGRO environment variable. To invoke this
+feature, select the Shell Edit command or press ctrl+Z. The grabber will try
+to invoke the tool on the original version of the file if it knows where you
+grabbed the data from in the first place, or otherwise it will write the
+object out into a temporary file prior to editing.
+
+
+
+
+Datafiles can be saved using any of three compression types, selected from
+the list at the top right of the grabber screen, or with the '-c0', '-c1',
+and '-c2' options to dat. With type 0, the data is not compressed at all.
+Type 1 compresses each object individually, while type 2 uses global
+compression over the entire file. As a rule, global compression will give
+better results than per-object compression, but it should not be used if you
+intend to dynamically load specific objects with the load_datafile_object()
+function or "filename.dat#objectname" packfile syntax.
+
+
+There are also three strip modes for saving datafiles, selected with the
+File/Save Stripped command in the grabber, or using the '-s0', '-s1', and
+'-s2' options to dat. With zero stripping, all object properties are written
+to the datafile, which is normally what you will want. With strip mode 1,
+properties specific to the grabber (the ones describing the origins and
+dates of each object) are removed, which will marginally reduce the file
+size, but will prevent the update command from working. For the smallest
+possible file sizes, strip mode 2 removes all properties, including object
+names and any custom properties you have added. This level of stripping
+should obviously be used with extreme caution, although in some cases it may
+be possible to recover the object names even after they have been stripped
+out of the datafile. If the grabber and dat utilities cannot find any name
+properties in a datafile, they will look for a header (.h) file with the
+same name, and attempt to parse this to recover the names. This is far from
+foolproof, and will not work for nested datafiles, but in some situations
+it allows the names to be read back from the index definition header. In
+addition to those three strip modes, you can define properties to be kept,
+whatever the strip mode. For example, if you want to strip all properties
+but the NAME, this command will do the job:
+
+
+ dat -s2 -s-NAME file.dat
+
+
+
+The objects of the datafile can be sorted alphabetically by name. This is
+selected by the Sort checkbox in the grabber, or by using the '-n0' and
+'-n1' options to dat. With zero sorting, objects are listed in the order
+they were added to the datafile. With sort level 1, they are listed in
+alphabetical order according to their NAME property, including inside
+nested datafiles.
+
+
+
+
+Both the grabber and the dat utility have an update command, which scans
+through the datafile checking if any objects have changed, and replacing
+those which are out of date. This depends on the origin and date properties
+which were set when the data was grabbed in the first place, so it won't
+work if these properties have been stripped out of the file. This command
+can be very useful if you build a datafile containing hundreds of objects
+grabbed from external bitmaps, and later go back and change some of these
+bitmaps. Rather than having to figure out which objects are out of date and
+then manually re-grab all the affected data, the update command will
+automatically refresh the modified objects.
+
+
+
+
+Fonts can be read from GRX format .fnt files, 8x8 or 8x16 BIOS format .fnt
+files, and from bitmap images, or you can import a multiple-range Unicode
+font by writing a .txt script that specifies a number of different source
+files for each range of characters. The script file contains a number of
+lines in the format "filename start end", which specify the source file for
+that range of characters, the Unicode value of the first character in the
+range, and the end character in the range (optional, if left out, the entire
+input file will be grabbed). If the filename is replaced by a hyphen, more
+characters will be grabbed from the previous input file. For example, the
+script:
+
+
+would import the first 96 characters from ascii.fnt as the range 0x20-0x7F,
+the next 96 characters from ascii.fnt as the range 0xA0-0xFF, and the entire
+contents of dingbats.fnt starting at Unicode position 0x1000.
+
+
+When reading a font from a bitmap file, the size of each character is
+determined by the layout of the image, which should be a rectangular grid
+containing all the ASCII characters from space (32) up to the tilde (126),
+unless you are using the script mechanism described above, in which case the
+range(s) should match the one(s) specified in the .txt file. The spaces
+between each letter should be filled with color 255. If each character is
+sized exactly 8x8 or 8x16 the grabber will create a fixed size font,
+otherwise it will make a proportional font. Probably the easiest way
+to get to grips with how this works is to load up the demo.dat file and
+export the TITLE_FONT into a PCX file. Have a look at the resulting picture
+in your paint program: that is the format a font should be in...
+
+
+
+
+Bitmap and RLE sprites can store an alpha channel along with the color
+information, as long as they are in a 32 bit format. Alpha data can be read
+directly from 32 bit TGA files, or you can use the alpha channel commands
+(in the Object menu, or the right mouse button popup menu) to import a
+greyscale alpha image over the top of an existing object. This menu also
+contains options for viewing the alpha channel of the selected object,
+exporting the alpha data to a greyscale image file, and deleting the alpha
+data to leave only pure color information. You can also use the File menu to
+import an alpha channel over the top of a bitmap that you have loaded with
+the Read Bitmap command, after which the alpha information will be included
+when you next perform a Grab or Grab From Grid operation.
+
+
+
+
+Datafiles can be encrypted with a password, by typing it into the
+"Password:" field in the grabber, or using the '-007 password' option to the
+dat utility. Passwords may be up to 256 characters in length, and are case
+sensitive. Encrypted files _cannot_ be read without the password, so please
+don't forget it and then come crying to me for help :-) To read an encrypted
+file into your program, call the packfile_password() function before
+load_datafile(). It is also a good idea to call packfile_password(NULL)
+afterwards, to set everything back to normal.
+
+
+
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/help.html b/lib/allegro/allegro-htmldocs-4.2.1/help.html
new file mode 100644
index 0000000..784c8be
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/help.html
@@ -0,0 +1,436 @@
+
+
+What to do when your Allegro program doesn't work
+
+
+
+
+
+What to do when your Allegro program doesn't work
+
+ When things go wrong, it often seems like a good idea to ask other people
+ for help. Fortunately for people in this situation, there are many people
+ (both Allegro developers and users) who are happy to spend their time
+ answering support questions of this type, but there are various things
+ you can do to make this process work more efficiently. This document
+ describes some steps to take whenever you have a problem with an Allegro
+ program, suggesting ways that you can try to solve it yourself, and also
+ giving some tips about when/how to ask for help. Following these
+ guidelines will make life easier both for the helper (because all the
+ relevant information will be presented to them in a concise and useful
+ way), and for the helpee (because they are more likely to get a prompt
+ and accurate reply).
+
+
+
+
+ Is the problem a bug in Allegro, or in your code? To find out, try
+ running the Allegro test programs, in particular the test.exe (for
+ graphics related problems), the play.exe (for soundcard troubles), and
+ the entire contents of the examples directory (for anything that is going
+ wrong). If you can't reproduce the problem with any of these, it is
+ probably your fault, in which case you should skip to part 3 below.
+
+
+ If the problem is related to DOS graphics modes, you should start by
+ getting a copy of Display Doctor from http://www.scitechsoft.com/.
+ If this fixes the trouble, it almost certainly means that your original
+ VESA driver was broken in some way. I'm not interested in hearing reports
+ about problems of this type: there is nothing I can do to fix them, so
+ I'm afraid your only option is to get a better VESA driver, for instance
+ by downloading Display Doctor. This is now free for download from SciTech's
+ website, but there is no longer support for it. Alternatively, you can see
+ if there is a FreeBE/AF driver for your card (see
+ http://www.talula.demon.co.uk/freebe/).
+
+
+ For Windows graphics modes, you should probably check if DirectX is
+ installed properly on your system and if new drivers have been released for
+ your card.
+
+
+
+
+ If you still think the problem lies with Allegro, post a system report
+ containing a description of the problem, what platform and library
+ version you are using, your hardware specs, and a list of exactly which
+ programs you were able to reproduce the problem with (it is important to
+ know not only what programs had trouble, but also which ones worked
+ correctly, if any).
+
+
+ Try running the test.exe program with various display drivers (any native
+ drivers that you think might work with your card), and in various video
+ modes, and report exactly what modes and color depths cause problems. If
+ you are able to use any high resolutions at all, run test.exe with the
+ Autodetect option and report the entire text that it displays in the
+ middle of the screen.
+
+
+ If the problem is related to DOS graphics modes, you should also post the
+ output from running the afinfo and vesainfo programs (the short version
+ is enough unless you are explicitly asked to add the -v switch: all that
+ extra data isn't usually needed).
+
+
+ If the problem is related to the sound system, try using the setup
+ program to manually configure your card. You may need to manually enter
+ the hardware parameters, and if it is an SB clone card, try selecting
+ some earlier breed of SB card than whatever it is autodetecting (SB Pro,
+ SB 2.0, or SB 1.0). If you are still unable to get anything working, your
+ post should include the name and descriptions of whatever digital and
+ MIDI sound drivers are being autodetected (this information is displayed
+ by the play.exe program).
+
+
+
+
+ When a djgpp program crashes, you will usually get a stack traceback
+ looking something like:
+
+ Exiting due to signal SIGSEGV
+ General Protection Fault at eip=00001eca
+ [snip]
+
+ Call frame traceback EIPs:
+ 0x00001eca
+ 0x00001590
+ 0x00001aea
+
+ This information tells you exactly where the crash occurred. To make
+ sense of it, you should compile your program with debugging information
+ (using the -g switch), and then run "symify program.exe" while this
+ traceback is displayed onscreen. That will change the traceback to
+ something along the lines of:
+
+ Call frame traceback EIPs:
+ 0x00001eca _strcpy+14
+ 0x00001590 _main+56, line 7 of t.c
+ 0x00001aea ___crt1_startup+138
+
+ In this case, you can see that the crash occurred in the strcpy()
+ function, which was called at line 7 of the main() function in the t.c
+ source file. Now you just have to go to that line, have a look at
+ whatever you are doing there, and change it to be correct :-)
+
+
+ Note: if the crash happens deep inside an Allegro function, this
+ traceback may not be so useful. When this happens you can recompile
+ Allegro with debugging information (see the readme file), and then
+ link your program with the debugging library version.
+
+
+ Note 2: even when this crash traceback points to one of the Allegro
+ functions, that does not necessarily mean the Allegro routine is at
+ fault. Anything will crash if you pass it invalid parameters, so unless
+ you can duplicate the problem in one of the Allegro example programs, you
+ should start out by assuming that it is a case of operator error and
+ double-check exactly what you are passing to the Allegro function.
+
+
+ When your Allegro compiled Linux/Unix program crashes, you will usually
+ get a not very meaningful message along with a core dump:
+
+ Shutting down Allegro due to signal #11
+ Segment violation (core dumped)
+
+ Look at your filesystem: there should be a file named core or something
+ similar with information telling you exactly where the crash occurred.
+ If there is no core, check your environment settings, under bash this is
+ done with the 'ulimit -a' command. Usually 'ulimit -c unlimited'
+ somewhere in your login scripts should work fine.
+
+
+ Just like with djgpp, to make sense of the core, you should compile your
+ program with debugging information (using the -g switch), and then run
+ the GNU debugger on it "gdb binary core". That will load the debugger,
+ print some information about linked libraries and leave you at a prompt.
+ Now you can get the full backtrace:
+
+ (gdb) backtrace
+ #0 0x08065237 in utf8_getx (s=0xbffffc5c) at ./src/unicode.c:347
+ #1 0x0806953f in ustrzcpy (dest=0x0, size=2147483646, src=0x0) at ./src/unicode.c:1770
+ #2 0x08057575 in _mangled_main () at t.c:9
+ #3 0x0806c9bf in main (argc=1, argv=0xbffffd14) at ./src/unix/umain.c:39
+ #4 0x4015414f in __libc_start_main () from /lib/libc.so.6
+
+ In this case, you can see that the crash occurred in the ustrzcpy()
+ function, which was called at line 9 of the main() function in the t.c
+ source file. Now you just have to go to that line, have a look at
+ whatever you are doing there, and change it to be correct :-)
+
+
+ Note that the crash happened deep inside an Allegro function, which is
+ also revealed by the traceback. However, the binary was linked against a
+ static debug version of Allegro, we wouldn't have had so much luck with
+ a non debug or dynamically linked version.
+
+
+ Since gdb is an interactive debugger, you could also select a frame and
+ check out the values of the variables, to see better who is the culprit:
+
+ Yuck! Playing with NULL values doesn't really pay off. Ok, while this was
+ a slightly out-of-the-can example, you surely get the point. Remember to
+ check out GDB's manual to learn about more useful commands and/or how to
+ debug your program while it's running and many other things. You might also
+ want to check out Peter Wang's "Debugging with GDB" article, featured in
+ the ninth number of the Pixelate online magazine
+ (http://pixwiki.bafsoft.com/).
+
+
+
+
+ One of the most common errors made by programmers is to neglect to check
+ the return value from a function that may fail. Such an error will often
+ lead to unexpected and downright unusual errors, making for a debugging
+ nightmare. There are many functions in and out of Allegro that may or may
+ not work depending on varying circumstances. They are, however, nice
+ enough to let you know whether or not they were successful through
+ documented return values.
+
+
+ Whenever you call a function that might fail (most importantly
+ set_gfx_mode(), install_sound(), and anything that loads data from the
+ disk), it is _essential_ that you check the return code from this, and
+ respond accordingly.
+
+
+ Another commonly forgotten but important tool is to use whatever option
+ enables strict warnings for your compiler (gcc uses -Wall), when
+ compiling your code. Any warnings reported by this option will almost
+ certainly represent errors in your program, and should be fixed before
+ doing anything else. When using gcc, a useful trick is to compile with
+ the -O setting as well, because this causes gcc to examine the program's
+ actions in more detail, enabling more useful warnings. You should
+ normally disable optimisation while debugging, though. Although it gives
+ better compile time warnings, it is likely to upset any debugging tools
+ that you later try to use.
+
+
+
+
+ Ok, so you've tried everything described above, and your program still
+ doesn't work. You have no idea what to do next, so it is time to cast
+ yourself unto the mercies of the net, in hopes of finding some kind of
+ wise man, seer, or oracle that holds an answer for your question...
+
+
+ The best places to ask are the Allegro mailing list (see readme.txt for
+ details) and the Allegro.cc forums. Please remember that the mailing list
+ is an Allegro-specific list. Problems relating to the C language or djgpp
+ compiler belong in other forums (comp.lang.c and comp.os.msdos.djgpp
+ respectively). The Allegro.cc forums can be found at
+ http://www.allegro.cc/. You can usually ask any question related
+ to Allegro here.
+
+
+ Both the Allegro and djgpp mailing lists are archived, and can be
+ searched via their respective homepages. It is very likely that you will
+ be able to find a solution to your problem by looking through the answers
+ to past questions, which will save you needing to post a query at all.
+
+
+ In accordance with proper netiquette, it is assumed that when you post to
+ any forum on the Internet you have at least consulted the relevant
+ documentation first, if not read it in its entirety. If the problem you
+ are having is worth asking hundreds of people the answer for, then it is
+ certainly worth taking a few minutes to try to solve the problem
+ yourself. Allegro is extensively and painstakingly documented and it is
+ considered a prerequisite to posting that you have not only read the
+ text, but examined the example programs as well.
+
+
+
+
+ Yes, people really do sometimes send me questions like this :-) Despite
+ years of practice I am still totally unable to read minds, so this is a
+ very pointless thing to ask. In order to get help with a problem you must
+ describe it in enough detail that other people will be able to understand
+ and reproduce it: this usually means posting some of your source code.
+
+
+
+ What not to do, Part Two:
+
+ "I've got a problem with my program. I'm attaching a 500k zip file
+ containing ten thousand lines of source code and all the graphics and
+ sound data: can you please debug it and tell me what the trouble is?"
+
+ After wasting the time and phone bills to download such a huge file, it
+ is unlikely that anyone will even _want_ to help you, let alone invest
+ the amount of time it would take to read and understand such a huge mess
+ of information. You must try to isolate a smaller chunk of code that
+ demonstrates the trouble: the smaller you can make it, the more chance
+ that someone will be able to help you with it. Remember that you are
+ asking other people to do you a favour, so it is your responsibility to
+ make this process as easy for them as you possibly can.
+
+
+
+
+ The most important thing is to include code that can be compiled and
+ tested by the person reading your message. Don't just post your entire
+ program: try to extract a small section that includes the specific lines
+ causing your problem, or reproduces the trouble in a simpler way (you
+ will often find that you can locate the error yourself in the process of
+ making this simpler version, so it is a good exercise in itself). This
+ code should be a small but complete program that can actually be compiled
+ and run, because it is very hard to debug incomplete code fragments.
+
+
+ It is best to include the code directly in the text of your email
+ message, because it is easier for people to read this than if they have
+ to extract it from an attachment.
+
+
+ Ideally your example should avoid using any external graphics and data
+ files. It is ok to include a small (max 2k) zip containing such
+ information, or failing that a description of what other files it needs
+ (eg. "put a 32x32 .pcx file called 'tile.pcx' into the same directory as
+ the program). If there is no way that you can simplify things this far,
+ you should upload the program and data to a website and then just post
+ that URL in your message.
+
+
+ You should say what compiler options you used to build the program. These
+ should include extra warnings. If you use gcc, post the list of compiler
+ switches you used.
+
+
+ Describe what you intended this program to do (it may not be instantly
+ obvious to other people), and also what it really does when you run it.
+ There is usually no need to post the actual crash traceback (other people
+ can duplicate this for themselves as long as they are able to compile and
+ run your code), but you should say whether you do get such a traceback,
+ or a lockup, or just incorrect results (and if so, in exactly what way
+ they differ from what you were expecting). It is useful to mark your
+ source with a comment to show what line the crash traceback points to.
+
+
+ Any other information that you can include may also be useful. Most
+ importantly a brief machine description, information about any relevant
+ drivers, and your Allegro version (please don't just say "WIP", but give
+ the exact date if you are using anything other than an official numbered
+ release).
+
+
+
+
+ For reference, here is an example of what I would consider to be an ideal
+ problem report:
+
+
+ I'm having some trouble using the hicolor video modes in my program,
+ although they work fine with the Allegro tests. I'm using Allegro 4.0
+ with MinGW 3.1.0 (gcc version 3.3.1) on a Pentium 1.2GHz, running under
+ Windows 2000 and an ATi Radeon 7000 videocard.
+
+ This program is supposed to select a 640x480 16 bit resolution, draw a
+ blue rectangle near the top left corner of the screen, and then wait for
+ a keypress before quitting, but I just get a General Protection Fault
+ when I run it.
+
+ I compile it using "gcc -Wall t.c -o t.exe -lalleg", and don't get any
+ warnings.
+
+
+ --- cut here, t.c ---
+
+ #include <stdio.h>
+ #include <allegro.h>
+
+ void main()
+ {
+ BITMAP *bmp = screen;
+
+ install_keyboard();
+
+ if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0) {
+ printf("Error setting video mode\n");
+ return;
+ }
+
+ set_color_depth(16);
+
+ /* crashes during this rectangle call! */
+ rectfill(bmp, 32, 32, 64, 64, 0x001F);
+
+ readkey();
+ }
+
+ Allegro is gift-ware. It was created by a number of people working in
+ cooperation, and is given to you freely as a gift. You may use, modify,
+ redistribute, and generally hack it about in any way you like, and you do
+ not have to give us anything in return.
+
+
+ However, if you like this product you are encouraged to thank us by making
+ a return gift to the Allegro community. This could be by writing an add-on
+ package, providing a useful bug report, making an improvement to the
+ library, or perhaps just releasing the sources of your program so that
+ other people can learn from them. If you redistribute parts of this code or
+ make a game using it, it would be nice if you mentioned Allegro somewhere
+ in the credits, but you are not required to do this. We trust you not to
+ abuse our generosity.
+
+
+ Disclaimer:
+
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+ SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+ FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/makedoc.html b/lib/allegro/allegro-htmldocs-4.2.1/makedoc.html
new file mode 100644
index 0000000..7bd5058
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/makedoc.html
@@ -0,0 +1,151 @@
+
+
+Not only the library is built from source code but the actual documentation
+too. Allegro is bundled with makedoc, a convulsed C program which started
+small and has grown to support many different output formats. The
+documentation source and documentation generator can be found both under the
+`docs/src' directory. Running `make' in Allegro's top directory will generate
+the documentation along with the library, but there are more specific make
+targets which you can use to selectively build only the documentation or
+specific versions of the documentation which by default won't be generated.
+You can find more about these in the "Makefile targets" chapter.
+
+
+Makedoc output will be placed in the `docs/format' directory or directly in
+the `docs' directory. Usually if an output format requires an external tool
+which doesn't come bundled with Allegro you will have to generate it manually
+with the correct makefile target.
+
+ `.txt'
+ Plain text version of the documentation. It is basically a dump of the
+ `._tx' source file stripping the custom tags. This output is generated by
+ default and available on all supported platforms.
+
+ `.rtf'
+ Rich text format version of the documentation. This is a slightly improved
+ version of the text output. Makedoc will generate a few nice things like
+ a table of contents and will use different fonts in the output, which
+ are nicer to read or print than the text version. This output is generated
+ by default and available on all supported platforms.
+
+ `.html'
+ Html version of the documentation. Depending on some tags in the `._tx'
+ source file it can be built as multiple files or a single big page (see
+ below). The documentation is generated in two steps: first the normal
+ output is generated. This output doesn't contain hyperlinks between
+ chapters since the makedoc tool doesn't know in advance in which file will
+ be found a specific symbol. The second pass will go through all the links
+ and make them point to the correct files. Thanks to cascade style sheets
+ you can customize the outlook of the documentation without having to
+ modify the makedoc tool. This output is generated by default and available
+ on all supported platforms.
+
+ `.3'
+ Unix man pages for the section "Library calls (functions within program
+ libraries)". As usual these man pages will contain a synopsis,
+ description and see also sections. Certain parts of the documentation
+ like chapter introductions won't have man pages. This output is generated
+ by default on Unix platforms. Note that you have to install the man pages
+ manually with a specific makefile target.
+
+ `.texi'
+ Intermediate format for GNU tools. This format is not readable alone and
+ requires processing to be transformed into something else. This output can
+ be generated on all platforms because it doesn't require external
+ programs, but all by itself is not very useful.
+
+ `.info'
+ GNU online info format. Generated from the `.texi' output this format can
+ be used with the GNU `info' tool. The produced output looks similar to the
+ plain text version but features hyperlinked navigation. This output is
+ generated by default on platforms supporting the GNU tools like Unix or
+ DJGPP (DOS). You need the `makeinfo' tool to generate the output and the
+ `info' tool to view it. You have to install this manually on your system
+ with a specific makefile target.
+
+ `.chm'
+ Compiled HTML. Similar to the HTML output but instead of having lots of
+ separate files you end up with a single file. You need Microsoft's HTML
+ compiler to build this version of the documentation. Windows users can
+ view `.chm' files by default. Non Windows users can go to
+ http://freshmeat.net/ and search for "chm viewer". Read more in the
+ "Makefile targets" chapter.
+
+ `.dvi'
+ Device independent documentation file. While this format is usable, it is
+ also used as intermediate step to other formats. In fact, this one is
+ build from the texi output. By default not build, as it relies on the
+ external tool texi2dvi.
+
+ `.ps'
+ Postscript version of the documentation, ideal for printing. This is not
+ generated by default because it needs to generate the DVI output and
+ then use the external tool `dvips'.
+
+ `.pdf'
+ Portable document format. Similar in output quality to the postscript
+ output, this has the advantage of having hyperlinks. Generated from the
+ texi output with the external tool `texi2pdf'.
+
+ `.devhelp'
+ Devhelp HTML + XML index format. Similar to the HTML output, this also
+ carries a separate index which can be used by external programs (usually
+ programming editors) to look up context sensitive help. Basically it is
+ like the info output but using the more flexible HTML format as base.
+ This format doesn't require external tools to be built, but it is not
+ built by default. You have to create and install it manually.
+
+ `.api'
+ SciTE api format. This is an index of all Allegro functions of the
+ library for the SciTE editor (http://www.scintilla.org/SciTE.html).
+ This output is generated by default and available on all supported
+ platforms.
+Some of the output formats can be customized even further by modifying some
+of the generated files or directly the original source file. The
+documentation source file format is described with more detail in
+`docs/src/makedoc/format.txt'. Usually the interesting bits to users are:
+
+ The HTML output generates by default individual HTML files for each
+ chapter. By uncommenting the `multiplefiles' command you can create a
+ single file with the whole manual. Note that external documentation files
+ like the FAQ or hacking guide will still be linked, but not included.
+
+ The HTML output also uses cascade style sheets to specify the outlook of
+ the generated pages. You can disable CSS with the `ignore_css' command or
+ specify a different CSS file with external-css=. The default CSS file
+ generated by makedoc also has something to tweak.
+
+ When using the multiple file output, makedoc places a "Back to contents"
+ link at the bottom of each chapter. If you follow a hyperlink you can end
+ up pointing at one of the last descriptions of the page but your browser
+ might not scroll to the correct height because the page ends up before.
+ To avoid this effect, you can uncomment one of the last lines in the CSS
+ related to a bottom margin. Making the bottom margin higher puts more
+ space between the "Back to contents" link and the physical end of the
+ page.
+
+Note that all the above which applies to HTML output also applies to
+documentation formats which are HTML based, like Devhelp or CHM.
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/mistakes.html b/lib/allegro/allegro-htmldocs-4.2.1/mistakes.html
new file mode 100644
index 0000000..8e7d219
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/mistakes.html
@@ -0,0 +1,113 @@
+
+
+Common mistakes
+
+
+
+
+
+ Most problems are addressed in this manual. If you aren't sure about
+ some parts of Allegro check particular section of manual. The FAQ
+ section can also be very useful.
+
+
+ On platforms that need it, Allegro uses END_OF_MAIN to
+ mangle your main() function and supply its own that is required by the
+ platform. Allegro assumes that main() returns an integer, as required
+ by various C standards. If you change the return type of your main() to
+ something else Allegro's main() will get confused and return some
+ nonsense value which some system can recognize as an error and crash
+ your program.
+
+
+ When loading a bitmap, Allegro will automatically create a bitmap big
+ enough to store it. In the above code the address returned by
+ create_bitmap() is overwritten by the second assignment statement, to
+ the return value of the call to load_bitmap(). Since the address of
+ the first (unnecessary) bitmap has been lost, there is no way to
+ destroy it so there is a memory leak.
+
+
+ Almost all Allegro functions require Allegro to be initialized first,
+ before they can be used. Since global object constructors are called
+ before main() (from where allegro_init() would be called) this
+ condition is violated. You need to postpone calls to Allegro functions
+ to after initializing Allegro.
+
+
+ set_color_depth() tells Allegro which color depth to use the next time a
+ graphic mode is set or bitmap is created or loaded. It doesn't change
+ the color depth of the current graphic mode or existing bitmaps. You
+ need to be sure that all your bitmaps and/or graphic mode are in the
+ same color depth or Allegro will be forced to do slow color conversions
+ between them.
+
+
+ Unlike other bitmaps `screen' is created by calling set_gfx_mode() and
+ must not be destroyed by calling destroy_bitmap(). The proper way to
+ destroy `screen' is calling set_gfx_mode(GFX_TEXT, 0, 0, 0, 0).
+
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/packfile.html b/lib/allegro/allegro-htmldocs-4.2.1/packfile.html
new file mode 100644
index 0000000..5fab7fe
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/packfile.html
@@ -0,0 +1,122 @@
+
+
+Packfile format
+
+
+
+
+
+ This document describes the format of Allegro's packfiles from a
+ decompression point of view. It does not describe how to do the
+ compression (read the source, or ask Google about LZSS).
+
+
+ file.c says "This compression algorithm is based on the ideas of Lempel
+ and Ziv, with the modifications suggested by Storer and Szymanski.", if
+ that means anything to you.
+
+
+
+ All compressed packfiles begin with a four byte signature "slh!" (ASCII),
+ which in hexadecimal is 0x73, 0x6C, 0x68, 0x21 (in that order).
+
+
+ Another form of packfiles are uncompressed packfiles, which begin with the
+ four byte signature "slh." (ASCII), in hexadecimal 0x73, 0x6C, 0x68, 0x2B.
+ The rest of the file is then completely raw. Uncompressed packfiles will
+ not be discussed further.
+
+
+
+ Decompression requires a ring buffer of 4096 bytes and a ring index (which
+ indexes into the ring buffer). The ring index starts at 4078, assuming
+ 0-based indices. New bytes may be stored into in the position in the ring
+ buffer that the index points to. When a byte is stored, the index is
+ incremented by one, wrapping around to zero as necessary.
+
+
+ Packfiles must be decompressed sequentially. The first byte following the
+ signature in the packfile is the "flags" byte, which determines how the
+ following "tokens" in the file are to be interpreted.
+
+
+ Bit 1 (the least significant bit) corresponds to the first token following
+ the flags byte. Bit 2 corresponds to the second token, etc. After every
+ eight tokens, there is another flag byte and another eight tokens, and so
+ on, until the end of file.
+
+
+ If the bit I of the flags byte is set, then token I is a single byte to be
+ sent to the output. In addition, it must put onto the ring buffer and the
+ ring index incremented.
+
+
+ Otherwise, if bit I of the flags byte is not set, then token I is a two
+ byte sequence containing an index and a length. The index is the first
+ byte OR'd together with the higher 4 bits of the second byte as the higher
+ order bits, thus making a 12-bit unsigned number (0-4095). The length is
+ the lower 4 bits of the second byte, plus 3.
+ In less hand-wavy C syntax:
+
+ Then, "length" number of bytes from the ring buffer, starting at "index",
+ are to be sent to the output. In addition, all these bytes must be put
+ onto the ring buffer, and the ring buffer incremented accordingly.
+
+
+ Decompression ends at the end of the file. There is no end-of-file
+ marker. If the number of tokens is not a multiple of eight, the unused
+ bits in the latest flags byte are always zero.
+
+
+
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/readme.html b/lib/allegro/allegro-htmldocs-4.2.1/readme.html
new file mode 100644
index 0000000..bae74a1
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/readme.html
@@ -0,0 +1,392 @@
+
+
+A general introduction to Allegro
+
+
+
+
+
+ ______ ___ ___
+ /\ _ \ /\_ \ /\_ \
+ \ \ \L\ \\//\ \ \//\ \ __ __ _ __ ___
+ \ \ __ \ \ \ \ \ \ \ /'__`\ /'_ `\/\`'__\/ __`\
+ \ \ \/\ \ \_\ \_ \_\ \_/\ __//\ \L\ \ \ \//\ \L\ \
+ \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
+ \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
+ /\____/
+ \_/__/ Version 4.2.1
+
+
+ A game programming library.
+
+ By Shawn Hargreaves, Nov 26, 2006.
+
+ See the AUTHORS file for a
+ complete list of contributors.
+
+
+
+
+#include <std_disclaimer.h>
+
+ "I do not accept responsibility for any effects, adverse or otherwise,
+ that this code may have on you, your computer, your sanity, your dog,
+ and anything else that you can think of. Use it at your own risk."
+
+ Allegro is a cross-platform library intended for use in computer games
+ and other types of multimedia programming. It was initially conceived on
+ the Atari ST, but that platform sadly died during childbirth. After a
+ brief stay with Borland C, it was adopted by the fantastic djgpp
+ compiler, where it grew to maturity. In the fullness of time it gave
+ birth to children of its own, who went to live in such exotic locations
+ as DirectX and the X Server, but the entire family is now back together
+ again, living in harmony as a single portable entity. How about that for
+ a mixture of metaphors? :-)
+
+
+ A wide range of extension packages and add-on modules are also available,
+ which can be found in the "Library Extensions" section of the Allegro.cc
+ website, http://www.allegro.cc/.
+
+
+ According to the Oxford Companion to Music, Allegro is the Italian for
+ "quick, lively, bright". It is also a recursive acronym which stands for
+ "Allegro Low Level Game Routines".
+
+
+
+
+ For instructions on how to install Allegro, how to link your programs
+ with it, and any additional information specific to each of the supported
+ platforms, see one of the files included in the distribution package:
+
+ General API information can be found in the main manual, usually referred
+ to as docs/txt/allegro.txt, allegro.txt or simply "The Allegro manual"
+ throughout this document. The Allegro manual source is available as a set
+ of files in the docs/src directory. During the build process of the
+ library, these source files will be converted to HTML, TexInfo, and RTF
+ formats (among others) and placed in their respective doc/FORMAT
+ directory.
+
+
+ Information about changes in the API and deprecated features can be found
+ in docs/txt/api.txt (also available in HTML, TexInfo, and RTF format as
+ part of the Allegro manual).
+
+
+
+
+ Cross-platform support for DOS, Windows, Unix, BeOS, QNX and MacOS X
+ systems.
+
+ Drawing functions including putpixel, getpixel, lines, rectangles, flat
+ shaded, gouraud shaded, texture mapped, and z-buffered polygons, circles,
+ floodfill, bezier splines, patterned fills, masked, run length encoded,
+ and compiled sprites, blitting, bitmap scaling and rotation,
+ translucency/lighting, and text output with proportional fonts. Supports
+ clipping, and can draw directly to the screen or to memory bitmaps of any
+ size.
+
+ DOS graphics drivers for VGA mode 13h, mode-X (twenty three tweaked VGA
+ resolutions plus unchained 640x400 Xtended mode), and SVGA modes with 8,
+ 15, 16, 24, and 32 bit color depths, taking full advantage of VBE 2.0
+ linear framebuffers and the VBE/AF hardware accelerator API if they are
+ available. Additional video hardware support is available from the
+ FreeBE/AF project (http://www.talula.demon.co.uk/freebe/).
+
+ Windows graphics drivers using DirectX in fullscreen and windowed modes,
+ plus routines for drawing onto GDI device contexts.
+
+ Unix graphics drivers for X, DGA2, fbcon, SVGAlib, VBE/AF, mode-X, and
+ standard VGA.
+
+ BeOS graphics drivers using BWindowScreen in fullscreen and BDirectWindow
+ in windowed modes.
+
+ MacOS X native graphics drivers using CGDirectDisplay API for direct
+ fullscreen gfx access and QuickDraw in a Cocoa window in windowed mode.
+
+ Hardware scrolling and triple buffering (where available), mode-X split
+ screens, and palette manipulation.
+
+ FLI/FLC animation player.
+
+ Plays background MIDI music and up to 64 simultaneous sound effects, and
+ can record sample waveforms and MIDI input. Samples can be looped
+ (forwards, backwards, or bidirectionally), and the volume, pan, pitch,
+ etc, can be adjusted while they are playing. The MIDI player responds to
+ note on, note off, main volume, pan, pitch bend, and program change
+ messages, using the General MIDI patch set and drum mappings. DOS version
+ currently supports Adlib, SB, SB Pro, SB16, AWE32, MPU-401, ESS
+ AudioDrive, Ensoniq Soundscape, and Windows Sound System. Windows version
+ supports WaveOut and DirectSound interfaces and the system MIDI drivers.
+ Unix version supports OSS, ESD, and ALSA sound drivers. BeOS version
+ supports BSoundPlayer and BMidiSynth interfaces. MacOS X native version
+ supports CoreAudio, Carbon Sound Manager and QuickTime Note Allocator
+ interfaces. All versions provide software wavetable MIDI playback.
+
+ Easy access to the mouse, keyboard, joystick, and high resolution timer
+ interrupts, including a vertical retrace interrupt simulator in the DOS
+ version.
+
+ Routines for reading and writing LZSS compressed files.
+
+ Multi-object data files and a grabber utility.
+
+ Math functions including fixed point arithmetic, lookup table trig, and
+ 3d vector/matrix/quaternion manipulation.
+
+ GUI dialog manager and file selector.
+
+ Built-in support for 16-bit and UTF-8 format Unicode characters.
+
+ Allegro is gift-ware. It was created by a number of people working in
+ cooperation, and is given to you freely as a gift. You may use, modify,
+ redistribute, and generally hack it about in any way you like, and you do
+ not have to give us anything in return. However, if you like this product
+ you are encouraged to thank us by making a return gift to the Allegro
+ community. This could be by writing an add-on package, providing a useful
+ bug report, making an improvement to the library, or perhaps just
+ releasing the sources of your program so that other people can learn from
+ them. If you redistribute parts of this code or make a game using it, it
+ would be nice if you mentioned Allegro somewhere in the credits, but you
+ are not required to do this. We trust you not to abuse our generosity.
+
+
+ Disclaimer:
+
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+ SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+ FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.
+
+
+ Allegro reads information about your hardware from a file called
+ allegro.cfg. If this file doesn't exist it will autodetect (ie. guess :-)
+ You can write your config file by hand with a text editor, or you can use
+ the setup utility program (located in the setup directory).
+
+
+ Normally the setup program and allegro.cfg will go in the same directory
+ as the Allegro program they are controlling. This is fine for the end
+ user, but it can be a pain for a programmer using Allegro because you may
+ have several programs in different directories and want to use a single
+ allegro.cfg for all of them. If this is the case you can set the
+ environment variable ALLEGRO to the directory containing your
+ allegro.cfg, and Allegro will look there if there is no allegro.cfg in
+ the current directory.
+
+
+ The mapping tables used to store different keyboard layouts are stored in
+ a file called keyboard.dat. This must either be located in the same
+ directory as your Allegro program, or in the directory pointed to by the
+ ALLEGRO environment variable. If you want to support different
+ international keyboard layouts, you must distribute a copy of
+ keyboard.dat along with your program.
+
+
+ Various translations of things like the system error messages are stored
+ in a file called language.dat. This must either be located in the same
+ directory as your Allegro program, or in the directory pointed to by the
+ ALLEGRO environment variable. If you want to support non-English versions
+ of these strings, you must distribute a copy of language.dat along with
+ your program.
+
+
+ Under Unix, BeOS and MacOS X, the config file routines also check for
+ ~/allegro.cfg, ~/.allegrorc, /etc/allegro.cfg, and /etc/allegrorc, in
+ that order, and the keyboard and language files can be stored in your
+ home directory or in /etc/. If under MacOS X, the application bundle
+ Contents/Resources directory, if any, is also scanned first.
+
+
+ The DIGMID wavetable driver uses standard GUS format .pat files, and you
+ will need a collection of such instruments before you can use it. This
+ can either be in the standard GUS format (a set of .pat files and a
+ default.cfg index), or a patches.dat file as produced by the pat2dat
+ utility. You can also use pat2dat to convert AWE32 SoundFont banks into
+ the patches.dat format, and if you list some MIDI files on the command
+ line it will filter the sample set to only include the instruments that
+ are actually used by those tunes, so it can be useful for getting rid of
+ unused instruments when you are preparing to distribute a game. See the
+ Allegro website for some links to suitable sample sets.
+
+
+ The DIGMID driver normally only loads the patches needed for each song
+ when the tune is first played. This reduces the memory usage, but can
+ result in a longish delay the first time you play each MIDI file. If you
+ prefer to load the entire patch set in one go, call the
+ load_midi_patches() function.
+
+
+ The CPU sample mixing code can support between 1 and 64 voices, going up
+ in powers of two (ie. either 1, 2, 4, 8, 16, 32, or 64 channels). By
+ default it provides 8 digital voices, or 8 digital plus 24 MIDI voices (a
+ total of 32) if the DIGMID driver is in use. But the more voices, the
+ lower the output volume and quality, so you may wish to change this by
+ calling the reserve_voices() function or setting the digi_voices and
+ midi_voices parameters in allegro.cfg.
+
+
+
+
+
+ This list is for any kind of discussion about Allegro, questions about
+ Allegro, reports of problems with Allegro, suggestions for new
+ features, announcements of programs written using Allegro, etc.
+ General rule: if it has to do with Allegro, you can post it here. If
+ not, go somewhere else (for example comp.os.msdos.djgpp, comp.lang.c,
+ or the online forums at http://www.allegro.cc/).
+
+
+ This list is for the people currently working on Allegro, who use it to
+ coordinate their efforts. You can use this address if you need to
+ contact the developers directly, for example to submit some new code
+ that you have written or to report a bug.
+
+ Unlike the other lists, we will be really rude to people who post
+ inappropriate material here, so please don't do that! Do not send
+ tech-support questions to this list. Don't post bug reports here unless
+ you are 100% certain they aren't your fault (if you are in any doubt,
+ use the main Allegro list instead, which is read by most of the same
+ people who are subscribed here).
+
+ The Allegro development is a completely open process, and everyone is
+ welcome to drop by, have a listen, and start contributing code patches.
+ This list is for working rather than talking, though, so please don't
+ do anything that might get in our way.
+
+
+ This list was once available for discussing the next major version of
+ Allegro, when it was too noisy to do so on [AD]. This is no longer the
+ case so the list has been shut down. However, its archives are still
+ valuable.
+
+ To subscribe to one of the three lists, simply go to it's web page and use
+ the online forms to subscribe yourself. You can remove yourself from a
+ list going to the same page above, which can be used to remind you of your
+ password too, in case you have forgotten it.
+
+
+ To send a message to one of the lists, write to
+ alleg-main@lists.sourceforge.net or
+ alleg-developers@lists.sourceforge.net. You don't need to be subscribed to
+ these mailing lists before you can post there, but it is a good idea to
+ subscribe in order to see the replies.
+
+
+ Before posting tech-support questions to the Allegro list, please take a
+ moment to read the guidelines in docs/txt/help.txt. See docs/txt/ahack.txt
+ for information about the style of code we use, and how to create your
+ patches.
+
+
+ If you want to search through the archives of any of those mailing lists,
+ you will have to check the available options at
+ http://alleg.sourceforge.net/maillist.html.
+
+
+ Please don't send messages in HTML format. The increased size places an
+ unnecessary load on the server, and many subscribers have a hard time
+ reading these posts.
+
+
+ Please do not crosspost between these lists. Choose the most appropriate
+ one for your message, and then send it only to that list.
+
+
+ Please don't send large binary attachments to any of the lists, they will
+ be rejected by the size limit filter, which is set to 100KB for the
+ developers mailing list, and 40KB for the others. Upload your files to a
+ website and then post the URL, or if you can't do that, post an
+ announcement asking people to write to you privately, and then send the
+ file by individual email to whoever responded.
+
+
+ Please use English in your messages. You could eventually post messages in
+ whatever language you prefer, but that would terribly limit the chances of
+ getting a useful answer.
+
+
+ Remember that the RFC 1855: netiquette guidelines
+ (http://www.rfc-editor.org/rfc/rfc1855.txt) describes other general
+ guidelines you should follow as a correct internet user (in mailing lists
+ and other places as well), and provides more verbose descriptions and
+ explanations about why you should follow the above guidelines.
+
+
+ One of the important guidelines you should be aware of is how to quote
+ correctly the message you are replying to. The previous RFC doesn't really
+ explain how to do it, so you might want to read the document "How do I
+ quote correctly in Usenet?" at
+ http://www.netmeister.org/news/learn2quote.html. Quoting correctly is
+ easier to say than to do, especially for users of Microsoft Outlook. If
+ you are such a user, you can help yourself using the Outlook-QuoteFix
+ extension written by Dominik Jain, which you can find at
+ http://home.in.tum.de/~jain/software/outlook-quotefix/.
+
+
+
+
diff --git a/lib/allegro/allegro-htmldocs-4.2.1/thanks.html b/lib/allegro/allegro-htmldocs-4.2.1/thanks.html
new file mode 100644
index 0000000..b6da7d8
--- /dev/null
+++ b/lib/allegro/allegro-htmldocs-4.2.1/thanks.html
@@ -0,0 +1,1495 @@
+
+
+Allegro Contributors
+
+
+
+
+
The Hall of Fame
+
+We hope to have remembered everyone who ought to be mentioned here. If your
+name should be included, accept our apologies, and please tell us so we can
+correct the oversight!
+
+
+
+
+ aj.
+ Reported many problems, suggested a lot of improvements to the
+ documentation, added AMD64/IA64/SSE3 detection code, added DirectX 8 and 9
+ detection to the Windows port, added MSVC7 specific options to the makefile,
+ cleaned up a C99-ism in makedoc, fixed a beep when alt+character was pressed
+ in windowed mode in Windows and made TARGET_ARCH_EXCL also work with MSVC.
+
+
+ Alex Demko (alex_demko at mbnet dot mb dot ca).
+ Suggested lots of improvements to the datafile system and provided code
+ for handling the 8x16 BIOS font format.
+
+
+ Alessandro Monopoli (almonopo at tin dot it).
+ Added the Italian translation of the system messages.
+
+
+ Andreas Kluge (bitland at aol dot com).
+ Wrote the Ensoniq Soundscape driver and fixed division bugs in the fix
+ class.
+
+
+ Andrei Ellman (ae-a-alleg2 at wacko dot wackonet dot net).
+ Contributed the polygon_z_normal() function, suggested some additions to
+ the docs, updated the Cygwin section in docs/build/mingw32.txt, got
+ Allegro for MSVC to build with Cygwin, improved the performance of the
+ hsv_to_rgb() function, corrected a rounding issue in hsv_to_rgb(),
+ improved the exrgbhsv example and the Windows screensaver, fixed problems
+ in the MSVC makefile when using Cygwin and did plenty of other things too.
+
+
+ Andrew Cottrell (andrewc at dbworld dot net dot au).
+ Changed the grabber to use a more robust (locale-independent) date format.
+
+
+ Andrew Ellem (krand at ican dot net).
+ Wrote the original version of the digital audio streaming code.
+
+
+ Andrew Geers (andy at geerswj dot clara dot net).
+ Added the -ppassword and -nosound options to the grabber, scrolling
+ support in the image viewer and the flipped rotated sprite routines.
+
+
+ Andy Goth (unununium at openverse dot com).
+ Made the gfx_card config variable more flexible, added the 256x256 tweaked
+ VGA mode, wrote the d_text_list_proc() dialog object and fixed the
+ constructor support in dat2s on Unix.
+
+
+ Angelo Mottola (a dot mottola at libero dot it).
+ Added the BeOS joystick, MIDI and windowed graphics drivers, added mouse
+ wheel, display switching and close button support for BeOS, wrote the
+ DGA2 driver and close button support for X, contributed the bfixicon
+ utility, added triple buffering support, a BWindow-based windowed driver
+ and a fullscreen overlay driver to the BeOS port and reorganized its gfx
+ subsystem. And, oh, contributed the QNX and MacOS X ports too.
+
+
+ Annie Testes (annie at kezako dot net).
+ Added font_height, render_char, char_length hooks to FONT_VTABLE, fixed
+ several glitches in the unicode support, added a pack_fdopen() function,
+ caught a misordering in the X system shutdown, fixed some device name
+ strings, lifted several hardcoded length limitations in the configuration
+ routines, added a mouse driver based on the event interface (EVDEV) to the
+ Linux port, fixed numerous bugs and did plenty of other things too.
+
+
+ Antti Haapala (ztane at lyseo dot edu dot ouka dot fi).
+ Fixed the setup program to display the right frequency list for each
+ type of soundcard and contributed the Finnish translation of the system
+ messages.
+
+
+ Ben Chauveau (bendomc at worldnet dot fr).
+ Added support for Tseng ET6000 cards (now available as part of the
+ FreeBE/AF project).
+
+
+ Ben Darnell (bdarnell at vnet dot net).
+ Put together the 2.11 release of Allegro while I was away from the net
+ and wrote the original version of the Allegro FAQ.
+
+
+ Ben Davis (entheh at users dot sf dot net).
+ Added set_volume_per_voice(), made silent voices continue playing,
+ fixed other minor bugs in the mixer, fixed a bug in create_rgb_table(),
+ adapted polygon functions to handle two coincident vertices, added the
+ set_window_close_button() and set_window_close_hook() framework, added
+ support for timers with parameters under Windows, corrected several
+ compilation warnings and documented the behaviour of pack_feof().
+
+
+ Benjamin Joel Stover (stovertech at intellisys dot net).
+ Wrote the initial version of the fullscreen X-Windows graphics driver.
+
+
+ Bertrand Coconnier (bcoconni at club-internet dot fr).
+ Modified 3D polygones routines for subpixel and subtexel accuracy, made
+ speed enhancements in these routines, fixed blending in C version of
+ atex_lit scanline functions, added scanline subdivisions in C scanline
+ functions and Z-buffer polygon functions and merged in Calin Andrian's
+ P3D library.
+
+
+ Bobby Ferris (baf at bafsoft dot com).
+ Added the SciTE API output format to makedoc and temporarily hosted
+ Allegro's SVN repository while SourceForge's SVN was in beta.
+
+
+ Burton Radons (loth at gec dot net).
+ Optimised the truecolor pixel blending function, converted the blenders
+ to the new single-handler format, and added the range of
+ Photoshop-compatible blender functions.
+
+
+ Calin Andrian (calin at ibd dot dbio dot ro).
+ Wrote the truecolor, MMX, 3DNow!, masked lit mode, translucent and
+ Z-buffered polygon rendering routines, the clip3d_f() function and also
+ the scanline sorting functions for 3D scene rendering, and his P3D
+ addon library was merged in.
+
+
+ Calvin French (frenchc at home dot com).
+ Added the -w (always update) switch to dat.exe.
+
+
+ Carsten Schmidt (email unknown).
+ Wrote the the initial version of the Linux GGI driver.
+
+
+ Carsten Sorensen (csorensen at ea dot com).
+ Wrote the the ESS AudioDrive soundcard driver.
+
+
+ Catatonic Porpoise ().
+ Added OpenBSD detection, fixed an issue with executable rights not set
+ on the memory for the i386 stretcher on UNIX systems, and fixed the
+ documentation for stretch_sprite.
+
+
+ Cloud Wu (cloudwu at 263 dot net).
+ Optimised the truecolor pixel blending functions.
+
+
+ Charles Bilyue (Esaelon at aol dot com).
+ Optimized the i386 blitters and suggested to not force yielding timeslice
+ with non-blocking menus.
+
+
+ Charles Wardlaw (kattkieru at yahoo dot com).
+ Fixed warnings with gcc 4 on MacOS X and helped resolve a problem with
+ setAppleMenu under Tiger.
+
+
+ Chris Jones (cj at jibblers dot plus dot com).
+ Fixed a bug with 16-bit samples loading, worked around a problem with DOS
+ file attributes under Win2k, let the MIDI player pass controller events to
+ the raw player by default, made the MIDI player handle the 'All Sound Off'
+ controller message, added support for the bitfield compressed BMP image
+ format, fixed the behavior of numeric keys when NumLock is on, and fixed
+ loading of certain .wav files.
+
+
+ Chris La Mantia (celamantia at home dot com).
+ Wrote the d_radio_proc(), d_icon_proc(), and d_slider_proc() dialog
+ objects, added the D_DISABLED flag, improved the GUI handling of
+ different font heights, and added the right aligned text functions.
+
+
+ Chris Robinson (crobin_99 at yahoo dot com).
+ Wrote the fixed point clip3d() function, improved the performance of the
+ DIGMID driver, implemented the digmid_set_pan function, rewrote part of
+ the Allegro mixer, made the Allegro mixer the default one in Windows,
+ improved the threaded UNIX timer code, helped improve responsiveness under
+ X11, tweaked tests/play.c, added drawing primitives and video bitmap locking
+ to the X11 port and did plenty of other things too.
+
+
+ Christer Sandberg (christer dot sandberg at mdh dot se).
+ Made dat2c work better with ISO C90 compilers, made dat2c correctly detect
+ the native line ending, fixed a problem with the include guard generated
+ by dat2c, fixed a bug in the 24-bit graphics code of fixup_datafile(),
+ fixed a problem with Electric Fence.
+
+
+ Christian Schueler (cschueler at gmx dot de).
+ Changed the optimisation settings for better performance.
+
+
+ Daniel Nilsson (daniel7 at algonet dot se).
+ Enlarged the starfield in exstars, and fixed an incorrect range in
+ exlights.
+
+
+ Daniel Schlyder (daniel at bitblaze dot com).
+ Fixed problems with get_executable_name() under Windows, another one with
+ set_window_title() under BeOS, potentially unsafe constructs in the
+ Windows code, the installall makefile target under Windows, added
+ set_allegro_resource_path(), fixed make uninstall with mingw make,
+ added ALLEGRO_LIB_BUILD flag for gcc variants not using configure,
+ fixed a bunch of warnings in MinGW and did plenty of other things too.
+
+
+ Daniel Verkamp (i_am_drv at users dot sourceforge dot net).
+ Added a MIDI input driver to the Windows port anda dded support for .rmi
+ MIDI files to the MIDI loader.
+
+
+ Dark Nation (email unknown).
+ Restored support for old-style encrypted packfiles, which had been removed
+ in 4.1.18.
+
+
+ David A. Capello (dacap at users dot sourceforge dot net).
+ Made dotted_rect() avoid bank switches, fixed a problem with lost GUI
+ mouse clicks, made d_menu_proc() steal/return focus when activated then
+ deactivated, fixed a problem with submenus, fixed a bug with FLI frames
+ containing odd-sized chunks, made makedoc write sub-section headings
+ for .txt output, made override_config_file also be used for writing to
+ the config file and did plenty of other things too.
+
+
+ Dave Thomson (gameskitchen at geocities dot com).
+ Added the RGB <-> HSV conversion routines, the autocrop function to
+ the grabber and wrote the 3d starfield example program (exstars.exe).
+
+
+ David Calvin (calvid at rpi dot edu).
+ Wrote the original version of the sound setup utility.
+
+
+ Deepak T (coolbool at gmx dot net).
+ Fixed clipping in three C sprite drawing routines.
+
+
+ Dennis Busch (email unknown).
+ Fixed a bug in d_clear_proc, fixed a Unicode bug in the mode selector,
+ and fixed the short description of add_clip_rect.
+
+
+ Dmitriy Kazimirow (mariann at mail dot ru).
+ Provided the Russian keyboard mapping and message translation files.
+
+
+ Dominique Biesmans (Dominique dot Biesmans at ping dot be).
+ Wrote the mode-X version of draw_sprite() and the mode-X <-> linear
+ blitting functions.
+
+
+ Eduard Bloch (edi at gmx dot de).
+ Fixed a freeze caused by the ESD detection code, fixed a bad behaviour
+ of the config routines and suggested better ways to find the path to
+ the executable on Unix.
+
+
+ Elias Pschernig (elias at users dot sf dot net).
+ Added a COLORCONV_KEEP_TRANS mode, contributed the wfixicon utility,
+ contributed several enhancements to the grabber, fixed menu dimensions in
+ the GUI engine, fixed the get_camera_matrix*() functions, added support
+ for the CHM and Devhelp documentation formats, fixed a bug in midi_seek(),
+ made load_datafile_object() load the object properties, made the GUI code
+ scare the mouse more intelligently and did plenty of other things too.
+
+
+ Eric Botcazou (ebotcazou at libertysurf dot fr).
+ Made the DGA driver work better in 8bpp and 32bpp modes, improved the
+ DirectX windowed driver and Windows graphics subsystem, partially
+ revamped the Unicode API and added uszprintf(), added file_select_ex(),
+ the unified al_find*() interface, an Unicode example, a new filetest,
+ rewrote the fixdll script, revamped the Borland C++ build process, fixed
+ lots of bugs and did plenty of other things too.
+
+
+ Erik Sandberg (eriksandberg at geocities dot com).
+ Optimised the 8 bit draw_sprite() and draw_trans_sprite() functions and
+ helped with the Swedish message translation.
+
+
+ Ettore Perazzoli (ettore at comm2000 dot it).
+ Optimised the linear -> mode-X blitting function.
+
+
+ Evert Glebbeek (eglebbk at dds dot nl).
+ Put set_gfx_mode on a diet, added a config entry for specifying the card
+ to be used for GFX_AUTODETECT_WINDOWED, added a '-fullscreen' switch to
+ the grabber, cleaned up the grabber/plugins code, added various commands
+ to the grabber, added the detection of SunOS/Solaris, added configure
+ options for x86 processor optimisations on Unix systems, added the support
+ for relative filenames and did plenty of other things too.
+
+
+ Fabian Nunez (faybs at iafrica dot com).
+ Added support for the CH Flightstick Pro and Logitech Wingman Extreme
+ joysticks, 3-button mice, and the extended keys on a Microsoft keyboard.
+
+
+ Fabrizio Gennari (faybs at iafrica dot com).
+ Contributed the DB9 and TurboGraFXoystick drivers.
+
+
+ Francisco Pires (fmlvp at hotmail dot com).
+ Added an FPS counter and an option to disable vsync to the excamera
+ example.
+
+
+ Francois Charton (deef at pobox dot oleane dot com).
+ Wrote the Paradise graphics driver (now available as part of the
+ FreeBE/AF project), improved the VGA palette setting code and helped
+ with the TexInfo conversion of the docs.
+
+
+ Garret Thomson (g at sirsonic dot com).
+ Wrote the music used in the demo game.
+
+
+ George Foot (gfoot at users dot sourceforge dot net).
+ Did a great deal of work on the Linux console version, wrote the AWE32
+ driver, added the MIDI pause/seek functions, provided the basis of the
+ SoundFont reader used in the pat2dat utility, fixed the C fceil()
+ function, added the ffloor() function and added non-FM support to the
+ OSS MIDI driver.
+
+
+ Grady Martin (shadygrady at budweiser dot com).
+ Fixed a bug in the handling of %n in the printf style text functions, added
+ a move command to the grabber and standardised some of the grabber dialog
+ boxes.
+
+
+ Grzegorz Adam Hankiewicz (gradha at users dot sourceforge dot net).
+ Wrote several of the example programs, suggested the "compress" makefile
+ target, translated the docs and system error messages into Spanish,
+ suggested the idea of embedding the setup utility into other programs,
+ wrote some documentation and corrected the .texi generation to improve
+ texi2dvi output, improved the makedoc utility and contributed a new doc
+ format, added reload_config_texts() and did plenty of other things too.
+
+
+ Grzegorz Godlewski (email unknown).
+ Contributed a Polish localization patch, and added support for lower and
+ upper altgr tables.
+
+
+ Grzegorz Ludorowski (pajonk at ajax dot umcs dot lublin dot pl).
+ Wrote several of the example programs, and made the intro animation and
+ graphics for the demo game.
+
+
+ Gunter Ladwig (gladwig at iname dot com).
+ Wrote the OS/2 detection routines and added the three-button mouse
+ emulation.
+
+
+ Hans de Goede.
+ Fixed a problem with dynamically generated stretcher code not being
+ properly marked as executable on Linux, fixed a busy wait in the X11 vsync
+ simulation, added a fullscreen driver for X11 which does not need XVidMode
+ extension, fixed a problem where switching to fullscreen mode under X11,
+ made digmid work with absolute pathes in patches.cfg, and fixed a problem
+ with the Alsa driver on big endian systems.
+
+
+ Harshavardhana Reddy N (nharsha at gmail dot com).
+ Added a Kannada greeting to exunicod.
+
+
+ Haruhiko Okumura (email unknown).
+ Wrote the original version of the LZSS compression code.
+ 12-2-404 Green Heights, 580 Nagasawa, Yokosuka 239, JP.
+
+
+ Hein Zelle (hein at icce dot rug dot nl).
+ Revamped the cross-compilation section of docs/build/mingw32.txt,
+ clarified a requirement when cross-compiling from Linux, reworked the
+ paragraph on the location of shared libraries under Unix in the docs and
+ added a FAQ entry on the same subject.
+
+
+ Henrik Schmidt (hbs at ks dot informatik dot uni-kiel dot de).
+ Found a workaround for the switching problem under Windows, made gcc pass
+ '-h' instead of '-soname' to the linker and replaced '-L' by '-h' in shell
+ comparisons so as not to break on Solaris.
+
+
+ Henrik Stokseth (hensto at online dot no).
+ Contributed a native Mingw32 port which can also be built with a
+ cross-compiler and the Cygwin compiler, much improved OS detection, added
+ get_gfx_mode_list() and methods for querying the VGA, Mode-X, Xtended,
+ VESA, VBE/AF and DirectX drivers for a list of possible GFX modes,
+ rewrote the mode-selector to use get_gfx_mode_list(), reworked the build
+ system many times and did plenty of other things too.
+
+
+ Hrvoje Ban (spoofer255 at gmail dot com).
+ Pointed out a bug in the mode selector, fixed several double ;'s, fixed
+ ASSERT() in Windows, helped write a documentation section about common
+ pitfalls, and added the create_datafile_index function.
+
+
+ Igor Gnip (gnipi at mindnever dot org).
+ Removed the requirements for fileutils on DOS/Windows platforms and added
+ the detection of MSYS to the MingW32 port.
+
+
+ Isaac Cruz (icruzbal at teleline dot es).
+ Fixed a bug with accelerated drawing onto sub bitmaps of DirectDraw
+ surfaces, added the GFX_DIRECTX_WIN driver, fixed a Windows sub bitmap
+ locking bug, added Windows desktop_color_depth and yield_timeslice
+ routines, and made extensive modifications to other aspects of the
+ Windows code.
+
+
+ Ivan Baldo (lubaldo at adinet dot com dot uy).
+ Wrote the 15/16 bit dithering code and optimised the sprite rotation
+ routines.
+
+
+ Jaime Moreno (daviangel at hotmail dot com).
+ Helped track down a problem with dependency generation in MacOS X.
+
+
+ James Hyman (frooge at mindless dot com).
+ Added support for quoted strings in the get_config_argv() function and
+ the dithering code for paletted images.
+
+
+ James Lohr (email unknown).
+ Fixed a problem with mouse acceleration in fullscreen modes under Windows.
+
+
+ James Ponder (james at squish dot net).
+ Suggested to remove the DJGPP makefile from the Unix tar archive and
+ clarified a requirement when cross-compiling from Linux.
+
+
+ Jason Wilkins (fenix at io dot com).
+ Wrote the quaternion math routines and contributed the BeOS port.
+
+
+ Javier Gonzalez (xaviergonz at hotmail dot com).
+ Corrected mouse movement speed, made allegro_message() use title from
+ set_window_title(), added close button hook support and improved
+ switching in Windows, fixed bad clearing of subbitmaps, made bug
+ reports and suggestions for improvement, contributed bidirectional
+ looping support, backward playing support and bugfixes for the
+ DirectSound driver and did plenty of other things too.
+
+
+ Jeff Mitchell (email unknown).
+ Fixed the location of grabber.txt in the spec file.
+
+
+ Jeremiah Blanchard (squirminworm at yahoo dot com).
+ Contributed modifications in order for Allegro to build on Darwin/MacOS X
+ and updated the build instructions for this new port afterwards.
+
+
+ Jim Flynn (jflynn at pacbell dot net).
+ Removed floating point calculations from the AWE32 MIDI driver.
+
+
+ Jiri Gabriel (email unknown).
+ fixed loading of multiple ranges in a single bitmap with txt fonts and helped
+ fix an off-by-one mistake for the last glyph in extract_font_range.
+
+
+ Joerg Rueppel (sharky-x at gmx dot net).
+ Added more flexible wildcard matching for object names in dat.exe and
+ the find_datafile_object() function.
+
+
+ Johan Peitz (d98peitz at dtek dot chalmers dot se).
+ Fixed and enhanced the Win32 joystick driver, and contributed the 'Alex
+ the Allegator' icon.
+
+
+ John Utz (Johnut01 at noa dot nintendo dot com).
+ Corrected a wrong assumption about the VRAM layout in the Linux
+ framebuffer console driver.
+
+
+ Jon Rafkind (workmin at ccs dot neu dot edu).
+ Added more ASSERTs to the code, implemented the Cohen-Sutherland clipping
+ algorithm for the line() function and supplied an m4 macro for allegro.
+
+
+ Jonathan Tarbox (jonattar at rocketmail dot com).
+ Wrote the mode-X setup code, the FLI/FLC player and contributed parts of
+ the joystick handler.
+
+
+ Jorrit Rouwe (j dot rouwe at cpedu dot rug dot nl).
+ Provided a new and much cooler set of FM instrument definitions for the
+ Adlib MIDI driver.
+
+
+ Jose Antonio Luque (skylord at LatinMail dot com).
+ Improved the Windows joystick driver, and optimised the 16-bit blit() and
+ masked_blit() functions.
+
+
+ J. P. Morris (email unknown).
+ Fixed a bug rest_callback under unix.
+
+
+ Julien Cugnière (jcugniere at free dot fr).
+ Improved the support for non-blocking menus, fixed a bug related to the
+ retrieval of the inital volume when no primary buffer was present under
+ Windows, fixed the crash on exit with the aRts sound driver, added an
+ X11 message box for allegro_message under X11 and fixed a crash in the GUI
+ when a dialog was opened while a menu was still open.
+
+
+ Laurence Withers (lwithers at users dot sf dot net).
+ Added destroy hook to font structure, worked on const-correctness
+ throughout the library, implemented the new FONT structure, made
+ some modules avoid linking dependencies, contributed the dat2c
+ utility, added two fixed point ratios for converting to and from
+ radians, added a '-windowed' switch to the grabber, added a new text
+ API and did plenty of other things too.
+
+
+ Lee Killough (email unknown).
+ Added the low-level hook routine to the keyboard handler and fixed a
+ couple of bugs.
+
+
+ Lennart Steinke (lst at steinke dot net).
+ Added the exconfig example, contributed keyboard layout detection code
+ for Windows and suggested the true colour font rendering.
+
+
+ Lisa Parratt (lisa at thecommune dot org dot uk).
+ Contributed the SGI Audio Library sound driver, spotted a BSDism that
+ IRIX doesn't like at all, added IRIX detection and improved the
+ performances of the SGI audio driver
+
+
+ Lorenzo Petrone (_lano_ at libero dot it).
+ Contributed the gfxinfo utility, added two FAQ entries, added a
+ xwin_set_window_name() function to the X11 port, added support for
+ switch callbacks under X11 and refactored the display switching code.
+
+
+ Lucas Vignoli Reis (lucasvr at bestway dot com dot br).
+ Added the Portuguese (Brazil) message translation and keyboard mapping.
+
+
+ Magnus Henoch (mange at freemail dot hu).
+ Made the gfx mode selector keep the current selection as much as possible
+ and fixed a problem when compiling without 8bpp support.
+
+
+ Marcel de Kogel (m dot dekogel at student dot utwente dot nl).
+ Not content with fixing my broken MPU-401 driver, Marcel went on to
+ provide a set of vastly improved drum sounds for the OPL driver, to help
+ me sort out some problems with reentrant interrupts, to supply the half
+ of the joystick code that didn't come from Jonathan and to locate a
+ stupid mistake in my VESA linear framebuffer code.
+
+
+ Marcel Smit (marcel dot athlon at hccnet dot nl).
+ Corrected a bug that caused errors when drawing persp. correct polygons
+ facing the screen, corrected an error in the packfile format write-up and
+ made the show_video_bitmap() method of the Windows windowed driver wait
+ for a vsync.
+
+
+ Márcio Fialho (maaf1980 at yahoo dot com dot br).
+ Fixed several issues with the DJGPP port and the VBE/AF driver and fixed
+ some bugs related to author credits.
+
+
+ Marco Campinoti (marco at etruscan dot li dot it).
+ Added 15 and 24 bit support to the native Tseng ET4000 driver (now
+ available as part of the FreeBE/AF project).
+
+
+ Marco Marmulla (Viper005 at usa dot net).
+ Added 16 bit support to the load_voc() routine.
+
+
+ Marian Dvorsky (marian at step dot sk).
+ Wrote the Windows GDI interface routines.
+
+
+ Marius Fodor (iceman at teleport dot com).
+ Added support for the Sidewinder and Gravis GamePad Pro.
+
+
+ Marek Habersack (grendel at ananke dot amu dot edu dot pl).
+ Did the original Linux console port (brave man: this was the first ever
+ work done on porting Allegro away from DOS), which is the basis of the
+ code we are still using today and added support for the more recent
+ Trident chipsets (now available as part of the FreeBE/AF project).
+
+
+ Mark Wodrich (mwodric at eleceng dot uct dot ac dot za).
+ The brain behind sub-bitmaps, flicker-free mouse pointers, and the
+ ability to import GRX .FNT files into the grabber.
+
+
+ Markus F.X.J. Oberhumer (markus dot oberhumer at jk dot uni-linz dot ac dot at).
+ Fixed the Video-7 scrolling function (now available as part of the
+ FreeBE/AF project), optimised the color mapping routines, and made many
+ useful suggestions like the addition of a vid_phys_base field to the
+ graphics driver structure.
+
+
+ Mathieu Lafon (mlafon at ifhamy dot insa-lyon dot fr).
+ Added the French keyboard mapping, support for the Pause/PrtScr keys and
+ changed the key[] table to a normal/extended bitfield.
+
+
+ Matt Witherspoon (spoon at vt dot edu).
+ Fixed a bug in the scroll() method of the Linux SVGAlib driver.
+
+
+ Matthew Bowie (catcat at nmt dot edu).
+ Added support for 4-button joysticks.
+
+
+ Matthew Leverton (matthew at allegro dot cc).
+ Fixed a bug with mouse mickeys in windowed mode under Windows, fixed a
+ problem with al_find*() and NTFS partitions under Windows, added missing
+ header files to be installed by the Windows binary distribution, made the
+ DOS/Windows makefiles use 'copy /B' instead of 'copy', added the detection
+ of left-hand mouse configuration under Windows, fixed a bug with
+ pack_fgets(), made an online diff generator and did lots of other things too.
+
+
+ Michael Bukin (M dot A dot Bukin at inp dot nsk dot su).
+ Ported the whole thing to Unix/X, and contributed a _lot_ of patches to
+ improve the portability, robustness, and performance of pretty much the
+ entire library.
+
+
+ Michael Faerber.
+ Pointed out a mistake in the documentation for text_height().
+
+
+ Michal Mertl (mime at eunet dot cz).
+ Wrote all the 24 bit graphics code, the optimised palette generation
+ function and a fair amount of the other truecolor stuff too (bitmap
+ scaling, image loading, etc).
+
+
+ Michal Molhanec (molhanec at seznam dot cz).
+ Simplified the build instructions for Dev-C++, replaced all occurences
+ of MingW32 by MinGW in the docs, added an faq section about the giftware
+ license, fixed problems with long filenames when building for MSVC,
+ corrected a problem with the Watcom port, added MSVC7 options to the
+ makefile, fixed a linker problem with the MSVC port, fixed some const
+ warnings in the grabber code and did plenty of other things too.
+
+
+ Milan Mimica (milan dot mimica1 at pu dot htnet dot hr).
+ Fixed bugs in the keyconf utility, the alsa 9 volume settings and
+ extract_font_range(), helped fix an off-by-one mistake for the last glyph
+ in extract_font_range, fixed a bug where a font would be converted to 8
+ bit, a bug with is_color_font, made the Linux console driver more robust,
+ fixed some spin loops in the test program, and added the get_volume and
+ get_hardware_volume functions, and did plenty of other things too.
+
+
+ Nathan Albury, aka Rubicant (gt4558a at prism dot gatech dot edu).
+ Improved the fire routine in examples/exflame.c (my original version
+ didn't really look very much like flames :-) and gave me some extremely
+ useful ideas about how to implement translucency.
+
+
+ Nathan Smith (white_door at dread dot nl).
+ Implemented the recursive handling of directories for the dat utility.
+
+
+ Neil Townsend (neil at robots dot ox dot ac dot uk).
+ Improved the accuracy of the timer routines and added the callback
+ parameters.
+
+
+ Ole Laursen (98zOLaw at aalborghus dot dk).
+ Contributed the Danish keyboard mapping table and system message
+ translation, and made the Unicode utolower() and utoupper() functions
+ understand the entire 16 bit character set.
+
+
+ Olly Betts (olly at muscat dot co dot uk).
+ Modified the djgpp makefile to support cross-compiling on a Linux machine.
+
+
+ Omar Cornut (cornut at noos dot fr).
+ Spotted an asm locking bug under Windows, bumped the maximum number of
+ buttons per joystick to 32, fixed the Windows joystick driver to handle a
+ weird peculiarity of the DirectInput API and improved the handling of
+ KEY_COLON2 on Japanese keyboards.
+
+
+ Oscar Giner (O_giner at hotmail dot com).
+ Added the Catalan translation, corrected the Spanish translation, fixed a
+ bug with binary data exporting in the grabber and fixed a conflict between
+ the magic main and the MFC.
+
+
+ Ove Kaaven (ovek at arcticnet dot no).
+ Fixed a bug in the ATI mach64 driver (now available as part of the
+ FreeBE/AF project), added native truecolor and linear framebuffer support
+ to the ATI driver, contributed the Norwegian keyboard mapping, and added
+ MIDI and sample input features to the MPU and SB drivers respectively.
+
+
+ Paavo Ahola (email unknown).
+ Helped fix a problem with BCC and the C implementations of fixmul.
+
+
+ Patrick Hogan (patter at iname dot com).
+ Wrote the draw_gouraud_sprite() function, and made Windows audiostreams
+ work properly.
+
+
+ Peter Cech (7cech at nw dot fmph dot uniba dot sk).
+ Added grabber support for the 8x8 BIOS font format, support for
+ hot-swapping between a custom keyboard layout and the standard US
+ mapping, optimised the alpha sprite blending routines and added non-ASCII
+ space recognition to uisspace().
+
+
+ Peter Hull (peterhull90 at users dot sourceforge dot net).
+ Made the file selector work with directories that have more than 2048
+ files, solved some compiling issues on MacOS X, fixed a bug in rest()
+ that caused it to wait too long on that platform, fixed several problems
+ with the hardware mouse cursor, fixed a deadlock in the software mouse
+ updating code, fixed compilation problems under MacOS X tiger, added a
+ MacOS X helpfile and did plenty of other things too.
+
+
+ Peter Johansson (email unknown).
+ Reported a problem with system cursors not working in Windows.
+
+
+ Peter Monks (pmonks at iname dot com).
+ Wrote the Video-7 graphics driver (now available as part of the FreeBE/AF
+ project) and showed me how to set up the unchained 640x400 mode.
+
+
+ Peter Pavlovic (Peter dot Pavlovic at st dot fmph dot uniba dot sk).
+ Added the Slovak keyboard mapping and message translation, stopped the
+ DOS file selector from listing virtual drives, did the same for the
+ Windows file selector, improved the support for accented character maps in
+ the keyboard driver and made aesthetic modifications to the GUI menu
+ system.
+
+
+ Peter Wang (tjaden at users dot sourceforge dot net).
+ Added the mouse_z wheel input support to the Linux code, fixed problems
+ with the ESD sound driver, wrote the ALSA sound driver, wrote the BeOS
+ sound driver, added OSS MIDI and sample input support, added banked mode
+ support to the SVGAlib driver, wrote the X DGA mode switching code,
+ improved the Linux joystick driver, X11 fullscreen, DGA2 and DGA driver,
+ added pthread timers under Linux/Unix and did loads of other things too.
+
+
+ Phil Shenk (email unknown).
+ Improved the MSVC build instructions.
+
+
+ Philipp Thomas (pthomas at suse dot de).
+ Fixed all comparisons between signed and unsigned types, fixed compilation
+ on x86-64, fixed all function prototypes, converted the configure
+ machinery to autoconf 2.53 or later and added multi-arch support, DESTDIR
+ support and the German translation to the RPM spec file.
+
+
+ Richard Mitton (100740 dot 1271 at compuserve dot com).
+ Added support for 6-button joysticks, and wrote the 12-bit color example
+ program (ex12bit.c).
+
+
+ Robert J. Ragno (rjr at mit dot edu).
+ Wrote the Gravis GrIP driver, made some improvements to the Wingman, PSX
+ and throttle input code.
+
+
+ Robert J. Ohannessian (voidstar at ifrance dot com).
+ Added MMX optimisation for the 8 and 16-bit clear() functions, fixed bad
+ clearing of subbitmaps, added SSE detection and optimised some masked
+ blits with SSE instructions, added some routines to the unified color
+ convertor and made some of them more robust, fixed the docs for
+ pivot_scaled_sprite_v_flip(), revamped the retrieval mechanism of CPU
+ capabilities, separated the CSS file and did plenty of other things too.
+
+
+ Roberto Alfonso (rpgrca at labint dot frba dot utn dot edu dot ar).
+ Fixed a couple of memory problems in the dat2c utility, added an
+ srand() call in the demo game, made the MSVC port call `link /lib'
+ rather than `lib', fixed several warnings with GCC 4 under DJGPP and
+ fixed a grabber crash when importing a font range in an existing font.
+
+
+ Robin Burrows (rburrows at bigfoot dot com).
+ Provided a new page flipping code for the DirectDraw subsytem, added a
+ Windows sound driver using the Allegro mixer and another using waveOut,
+ fixed two glitches in the DirectDraw code.
+
+
+ Salvador Eduardo Tropea (salvador at inti dot edu dot ar).
+ Improved the keyboard routines (better handling of extended scancodes,
+ keyboard LED support, capslock and numlock, and alt+numpad input),
+ contributed the 320x100 VGA graphics mode, added support for proper 16
+ bit sample mixing, fixed compilation on gcc 3.x and made numerous other
+ useful suggestions, contributions and bugfixes.
+
+
+ Sam Hocevar (sam at zoy dot org).
+ Fixed a Bashism in fix.sh that makes Solaris' sh choke, a race
+ condition in the mixer under Unix w/ threads, Windows, BeOS and MacOS X,
+ a crash in makedoc, made it possible to put functions from .s sources
+ in a shared library under Unix and removed deprecated use of several
+ functions.
+
+
+ Seunghwan Ji (email unknown).
+ Made makedoc output correct html and rtf files for Korean.
+
+
+ Serge Semashko (serge at lxnt dot info).
+ Fixed a bug with the letter P in the Russian keyboard configuration
+ file, added Enter as a fire key to the demo game, fixed some
+ problems with Allegro working on Nokia 770, and fixed a crash in
+ _linear_draw_trans_rgba_rle_sprite24.
+
+
+ Seymour Shlien (seymour at dgbt dot doc dot ca).
+ Contributed the Windows BMP file reader, bezier spline drawer, and
+ justified text plotting function.
+
+
+ Shawn Walker (binarycrusader at gmail dot com).
+ Several fixes to the .spec file, made get_executable_name use getexecname()
+ under Solaris, fixed a bug in the keyboard driver that caused crashes on
+ the same system, worked around errors with some versions of GNU AS and fixed
+ errors in the configure script when not using GCC
+
+
+ StApostol (stapostol at gmail dot com).
+ Fixed a bug in the exflame example and updated the FAQ to use rest(0) instead
+ of yield_timeslice().
+
+
+ Stepan Roh (src at srnet dot cz).
+ Added a Czech keyboard mapping and system message translation, the Latin
+ Extended-A characters in the default font, the codepage support in the
+ textconv utility, fixed some problems with the ESD sound driver, helped
+ make Allegro build better on some Unix platforms, fixed const related
+ problems in C versions of routines and added support for a automake-style
+ DESTDIR variable in the Unix makefile.
+
+
+ Stephan Brauss (sbrauss at optronic dot ch).
+ Made a few fixes to let the Linux port compile again on Linux 2.2.x,
+ corrected a few nits in the Swiss keyboard configuration file and added
+ new keysyms to the X11-to-BIOS conversion table in order to catch missing
+ keycodes for the keypad when NumLock is on.
+
+
+ Stijn Wolters.
+ Clarified the documentation of init_dialog.
+
+
+ Sveinung Kvilhaugsvik(email unknown).
+ Pointed out that Allegro should respect DESTDIR under MacOS X.
+
+
+ Sven Sandberg (svens at it dot uu dot se).
+ Fixed a problem with save_bitmap() rounding the image widths, optimised
+ the create_light_table() function, optimised the fixed point trigonometric
+ routines, provided the Swedish message translations, improved the file
+ selector sorting algorithm, optimised the spline routines, added
+ ustrrchr(), improved the usprintf() handling of floats, changed the
+ Z-buffer API, and did plenty of other things too.
+
+
+ TBD/FeR (tbd at usa dot net).
+ Added the 320x600 and 360x600 resolutions to the mode-X driver.
+
+
+ Theuzifan Sumachingun (uzi at simauria dot upv dot es).
+ Improved the cpu detection for Cyrix chips and made the file selector
+ only list valid drive letters.
+
+
+ Thomas Fjellstrom (tfjellstrom at home dot com).
+ Wrote the ALSA 0.5.x MIDI driver and added support for ALSA 0.9.x.
+
+
+ Thomas Harte (email unknown).
+ Helped fix a bug in show_video_bitmap() on MacOS X, helped optimise
+ fixmul(), helped find many bugs in the MacOS X port, like better support
+ for user-supplied Nibs, implemented a hardware accelerated stretch_blit
+ under DirectX, and fixed a bug with draw_sprite and sub-bitmaps.
+
+
+ Thomas Wolf (two at chello dot at).
+ Corrected some errors in the German keyboard mapping and added the
+ German translation of the system messages.
+
+
+ Tobi Vollebregt (email unknown).
+ Spotted a bug in ustrerror(), which was not returning a pointer to
+ a static buffer, reported a problem with shutdown_dialog() when a
+ menu was open, helped port the Windows keyboard driver to Windows 98
+ and fixed a bug with hardware cursor detection in X11.
+
+
+ Tobias Dammers.
+ Fixed a problem with the DirectSound input driver.
+
+
+ Tomohiko Sugiura (tmsugi at d4 dot dion dot ne dot jp).
+ Added the KEY_ABNT_C1, KEY_YEN, KEY_KANA, KEY_CONVERT, KEY_NOCONVERT
+ and other keys to the input handler, organised getting the IF-SEGA
+ joystick drivers by S.Suzuki merged into my codebase and added a more
+ aggressive Sidewinder joystick driver.
+
+
+ Tore Halse (gnolam at gmail dot com).
+ Made Allegro windows always popup centred in Windows and made fixes to the
+ documentation.
+
+
+ V Karthik Kumar (karthikkumar at gmail dot com).
+ Added a Tamil language greeting to exunicode, added switches to use
+ the Intel compiler in Windows and added a password option to the Windows
+ screensaver example.
+
+
+ Victor Williams Stafusa da Silva (vwss1984 at yahoo dot com dot br).
+ Changed a few occurences of "256" to PAL_SIZE and made OS type detection
+ handle Windows 2003 and Windows Vista.
+
+
+ Vincent Penquerc'h (lyrian at kezako dot net).
+ Added the D_DIRTY flag and mouse button press/release events to the GUI
+ system, optimised the 256 to truecolor blitting code to avoid repeated
+ conversions of the palette table, added scare_mouse_area(), added the
+ yield_timeslice() function, added the update selection function to the
+ grabber, added the XCRP and YCRP properties to datafiles in general,
+ implemented the big header split and did plenty of other things too.
+
+
+ Vitaliy Chetverikov (email unknown).
+ Fixed a bug in the GUI where the return value of MSG_IDLE was ignored.
+
+
+ VolkerOth (VolkerOth at aol dot com).
+ Integrated the concepts of scrolling and edit_proc objects.
+
+
+
+
+ First, a big thank you to all the people who help me test and debug this
+ code. It sometimes gets frustrating to receive hundreds of messages
+ saying "it doesn't work!", but they are useful all the same...
+
+
+ C. Schwerdtfeger (schwerdt at physics dot ubc dot ca),
+ for his help (and enourmous patience!) in getting the SB Pro-I MIDI
+ driver to work.
+
+
+ Finn Thoegersen, Nordbanevej 3 C, DK-7800 Skive, Denmark.
+ Most of my SVGA hardware information came from his VGADOC package.
+
+
+ Eric Jorgensen (smeagol at rt66 dot com).
+ Varmint's Audio Tools (VAT) gave me many useful ideas about how to play
+ MIDI files.
+
+
+ Jamie O'Connell (JamieOConnell at msn dot com).
+ Several of the new Adlib drum patches, and the specifications for the
+ .IBK file format, came from his SBTimbre package.
+
+
+ Jean-Paul Mikkers (mikmak at stack dot urc dot tue dot nl).
+ MikMod was the source of a lot of information about programming the SB,
+ and also gave me the idea of dynamically reprogramming the PIT to get a
+ really high resolution timer.
+
+
+ Kendall Bennett and all the other cool people at SciTech Software.
+ These guys gave the world UniVBE, the VBE/AF API, and a lot of free
+ information and example code. Plus they very kindly sent me a copy of the
+ VBE/AF spec when I wanted one.
+
+
+ Mark Feldman.
+ It goes without saying that the PCGPE was an invaluable resource.
+
+
+ Michael Abrash.
+ You just gotta love that man...
+
+
+ Paul Fenwick (bg914 at freenet dot carleton dot ca).
+ Various bits of the mode-X code (notably the split screen stuff) came
+ from his XLIBDJ library.
+
+
+ powerjaw (powerjaw at dnai dot com).
+ Sent me a Sidewinder gamepad so I could fix some problems with the driver
+ for it. What a cool thing to do...
+
+
+ Robert Grubbs (rwgrubbs at vt dot edu).
+ Provided hardware information for the Sidewinder joypad.
+
+
+ Robert Schmidt (robert at stud dot unit dot no).
+ The register values for the 400x* mode-X resolutions came from his TWEAK
+ program.
+
+
+ Sourceforge.net (http://sourceforge.net/).
+ The Allegro community has been using their services (web, mailing lists,
+ cvs, etc) since 3.9.x WIP versions.
+
+
+ Tom Grandgent (tgrand at canvaslink dot com).
+ Organised and hosted the original Allegro mailing lists for many years.
+ Hurrah!
+
+
+ Frank Zappa, Mike Keneally, Pink Floyd, the Doors, Tori Amos, and all the
+ other great musicians who provide me with things to listen to while I am
+ programming.
+
+
+ My parents, John and Nancy.
+ I would never have made it through all those late night coding sessions
+ without the cafetiere they gave me last Christmas :-)
+
+
+
Moved all sprites to PNG format.
+Added loadpng library, and with it libpng
+and zlib.
+Screenshots are now saved as png.
+No transparency is yet supported.
+
+
+
+
+
+
+
+
+
+
+
+
+
Go to:
+
+
+
+
+
+
+
+
+
+ Project members,
+ sign in to write a code review
Moved all sprites to PNG format.
+Added loadpng library, and with it libpng
+and zlib.
+Screenshots are now saved as png.
+No transparency is yet supported.
+
+
+
+
+
+
+
+
+
+
+
+
+
Go to:
+
+
+
+
+
+
+
+
+
+ Project members,
+ sign in to write a code review
+
+