diff options
Diffstat (limited to 'dumb/dumb-0.9.3/docs/howto.txt')
| -rw-r--r-- | dumb/dumb-0.9.3/docs/howto.txt | 864 |
1 files changed, 0 insertions, 864 deletions
diff --git a/dumb/dumb-0.9.3/docs/howto.txt b/dumb/dumb-0.9.3/docs/howto.txt deleted file mode 100644 index b9d1a1b2..00000000 --- a/dumb/dumb-0.9.3/docs/howto.txt +++ /dev/null @@ -1,864 +0,0 @@ -/* _______ ____ __ ___ ___ - * \ _ \ \ / \ / \ \ / / ' ' ' - * | | \ \ | | || | \/ | . . - * | | | | | | || ||\ /| | - * | | | | | | || || \/ | | ' ' ' - * | | | | | | || || | | . . - * | |_/ / \ \__// || | | - * /_______/ynamic \____/niversal /__\ /____\usic /| . . ibliotheque - * / \ - * / . \ - * howto.txt - How To Use DUMB. / / \ \ - * | < / \_ - * See readme.txt for general information on | \/ /\ / - * DUMB and how to set it up. \_ / > / - * | \ / / - * | ' / - * \__/ - */ - - -******************** -*** Introduction *** -******************** - - -Welcome to the DUMB How-To! It is assumed here that you have already set DUMB -up on your system, with or without Allegro. If not, please see readme.txt. - - -********************************* -*** Adding music to your game *** -********************************* - - -These instructions will help you add a piece of music to your game, assuming -your music is stored in a stand-alone IT, XM, S3M or MOD file. If you wish to -use a different method (such as putting the music file in an Allegro -datafile), please follow these instructions first, test your program, and -then follow the instructions further down for adapting your code. - - -1. You need to include DUMB's header file. If you have Allegro, add the - following line to the top of your source file (or at the top of each file - where you wish to use DUMB): - - #include <aldumb.h> - - If you do not have Allegro or do not wish to use it, use dumb.h instead. - - -2. You need to link with DUMB's library file or files. If you are compiling - with GCC from a command line on any platform, you need to add the - following to the command line: - - If you are using Allegro: -laldmd -ldumbd - If you are not using Allegro: -ldumbd - - If you are using MSVC from the command line: - - If you are using Allegro: /link aldmd.lib dumbd.lib - If you are not using Allegro: /link dumbd.lib - - With MSVC, you must also add /MD to the command line when compiling (not - when linking). - - Note that -laldmd or aldmd.lib must PRECEDE alleg.lib, -lalleg_s, - `allegro-config --libs`, or whatever you are already using to link with - Allegro. For MSVC users, the /MD flag selects the multithreaded DLL - implementation of the standard libraries; since DUMB is statically linked, - you have to use the same library DUMB uses. You would also need this flag - to link statically with Allegro; if you already have it, there's no need - to put it twice. - - (If anyone would like to contribute instructions for doing the above using - MSVC's IDE, please contact me. Contact details are at the end of this - file.) - - If you are using RHIDE, go to Options -> Libraries. You will need to type - 'aldmd' and 'dumbd' in two boxes, making sure 'aldmd' comes above whatever - you are using to link with Allegro (or just put 'dumbd' if you are not - using Allegro). Make sure the box next to each of these libraries is - checked. - - The above are the debugging libraries. It is VERY HIGHLY RECOMMENDED that - you use the debugging libraries at first. The reason is as follows. - Although DUMB is supposedly robust against corrupt music files and things - like lack of memory, it will NOT tolerate programmer error. If you write - faulty code, DUMB will probably crash rather than returning an error code - for you. However, the debugging libraries will abort in many cases, - enabling you to find out what the cause is. - - Once your program is up and running reliably, you can replace 'aldmd' with - 'aldmb' and 'dumbd' with 'dumb'. Don't forget to do this, or DUMB will be - a lot slower than it should be! - - -3. As you use DUMB, it may claim system resources (memory in particular). You - will need to arrange for these resources to be freed at the end. Doing so - is very easy. Simply write the following line at the top of your main - function, but below allegro_init() if you are using Allegro: - - atexit(&dumb_exit); - - This arranges for the function dumb_exit() to be called when your program - exits; you do not need to call dumb_exit() yourself. This method is - preferable to calling dumb_exit() manually, as it will free resources even - if your program aborts unexpectedly. - - If you are happy with this, please skip ahead to Step 4. If you are - interested in alternative methods, read on, but read on carefully. - - In fact it mostly doesn't matter where you put the above atexit() line, - provided it gets called only once, and before you do anything with DUMB. - If you are using DUMB with Allegro, it is recommended that you write the - functions in this order: - - allegro_init(); - atexit(&dumb_exit); - - And then you must NOT call allegro_exit() yourself (because it has to be - called after dumb_exit()). Alternatively, if you prefer not to use - atexit() (or you cannot), you will have to do the following before - exiting: - - dumb_exit(); - allegro_exit(); - - -4. DUMB does not automatically know how to open files. If you are loading - stand-alone files, you have to tell it how to open them. Don't worry, it's - easy. Simply call the following function near the beginning of your - program, after your atexit() call: - - dumb_register_stdfiles(); - - Once you've done this, a stdio FILE will be opened each time DUMB wants to - open a file (specifically, when dumbfile_open() is called). If you are - using Allegro and would rather DUMB used PACKFILEs, call the following - function instead: - - dumb_register_packfiles(); - - In the latter case, DUMB will be affected by any password you set with - packfile_password() in the same way that other PACKFILEs are. - - Note that the procedure for loading datafiles with embedded music is - independent of these two functions; even if you will be loading datafiles, - you can use either of these functions. dumb_register_stdfiles() will - probably be faster. If you are only ever going to load datafiles and never - stand-alone files, you can actually leave this step out; but I would - recommend you put this in, test your code with a stand-alone file, then - follow the instructions in the next section in order to adapt your code to - use the datafile (the instructions will remind you that you can remove the - function call). - - -5. If you are using Allegro, you will have to initialise Allegro's sound - system. In most cases the following line will do the job: - - install_sound(DIGI_AUTODETECT, MIDI_NONE, NULL); - - Put this line after allegro_init(). See Allegro's documentation if you - want to initialise a MIDI driver too. - - -6. All pieces of music are stored in memory in DUH structs. To handle these, - you must define pointers to them. Such pointers look like this: - - DUH *myduh; - - You can of course replace 'myduh' with anything you like. If you are - unfamiliar with pointers, please see ptr.txt. It is very important that - you understand these if you wish to use DUMB correctly. - - You do not have direct access to the contents of a DUH struct, because - they are liable to change. It is hoped that DUMB's functions will provide - everything you need; if you need something else, please let me know and I - shall see what I can do. Contact details are at the end of this file. - - Given the above definition, you can load a piece of music using one of the - following lines, depending on what file format you want to load: - - myduh = dumb_load_it_quick("a_one.it"); - myduh = dumb_load_xm_quick("a_two.xm"); - myduh = dumb_load_s3m_quick("a_one_two.s3m"); - myduh = dumb_load_mod_quick("three_four.mod"); - - You can use relative or absolute paths as normal. You should always use - forward slash (/), not backslash (\), when coding in C and similar - languages. - - There are non-"quick" versions of the functions too; for information on - what this means, please see dumb.txt. - - Every piece of music you load must be unloaded when you've finished with - it. When you type the above line in, it is good practice to type the - following line in at the same time, but put it at the end of the program: - - unload_duh(myduh); - - You will now be able to use the DUH struct anywhere in between the two - lines you just added. There is no need to check the return value; if the - DUH failed to load for one reason or another (this could be due to lack of - memory as well as the file not being there), then DUMB will do nothing - - safely. - - -7. From this step onwards, it will be assumed you're using Allegro. If not, - please read these steps anyway, and then see the section entitled - "Rendering music into a buffer". You will have to write your own playback - code using whatever sound output system is available. Alternatively you - may like to write data to a file (especially if you have a module that - consumes a lot of processor time). - - In order to play the DUH you loaded, you need to define a pointer to an - AL_DUH_PLAYER struct: - - AL_DUH_PLAYER *dp; - - Two of the functions you will need are prototyped as follows: - - AL_DUH_PLAYER *al_start_duh(DUH *duh, int n_channels, long pos, - float volume, long bufsize, int freq); - - void al_stop_duh(AL_DUH_PLAYER *dp); - - As you can see, al_start_duh() returns a pointer to an AL_DUH_PLAYER - struct when you call it. You then pass this pointer to all the other - functions. Again, if it is a NULL pointer for whatever reason (usually - lack of memory), DUMB will safely do nothing. When you call al_stop_duh(), - the pointer becomes invalid and you should not use it again; if there's - any risk of the pointer being used again, it is wise to set it to NULL at - this point. You can reassign the variable with a new call to - al_start_duh() of course. - - Set 'n_channels' to 1 or 2 for mono or stereo respectively. Note that this - parameter has nothing to do with the number of samples that can play at - once in a music module. Set 'pos' to 0 to play from the beginning; each - time you add 65536, you will have advanced one second into the piece. (If - you use the non-"quick" loaders, seeking like this will be faster.) As a - general rule, set the volume to 1.0f and adjust it later if the music is - too loud or too quiet - but see Allegro's set_volume_per_voice() function - first. - - 'bufsize' can generally be set to 4096. If your music stutters, try - increasing it; if your game freezes periodically, try reducing it. Find a - happy medium. Set 'freq' to 48000 for the best quality, though 44100 will - do in most cases. 22050 will be fine for a lot of music, though 11025 may - sound muffled. You can choose any other value, higher, lower or in - between. If your music stutters, and increasing 'bufsize' doesn't fix it, - try reducing this value. - - Once you have put in a call to al_start_duh(), it is good practice to - insert the call to al_stop_duh() at the same time. You must call - al_stop_duh() before the DUH is unloaded (unload_duh(), Step 6 above). - - Don't get impetuous, your program is not ready yet! Proceed to Step 8. - - -8. DUMB does not play music in the background for you; if you were expecting - it to do so, please see the explanation at the end of this step. For your - music to be played, you have to call another function at regular - intervals. Here is its prototype: - - int al_poll_duh(AL_DUH_PLAYER *dp); - - Do NOT call this function from inside a timer function unless you really - know what you are doing. The reasons why this is bad are explained - further down. You should call it from your main program. - - Simply writing the following line will be sufficient in general, if you - have a variable 'dp' that points to your AL_DUH_PLAYER struct. - - al_poll_duh(dp); - - As a general rule, calling this once for each logic update will do the - trick. If, however, you are executing time-consuming algorithms such as - software 3D rendering, you may wish to insert calls to this function in - the middle of those algorithms. You cannot call this function too often - (within reason); if it has nothing to do it will return immediately. - - Exactly how often you need to call the function depends on the values for - 'bufsize' and 'freq' that you passed to al_start_duh(): - - n = freq / bufsize; - - You have to call al_poll_duh() at least n times a second. Do not hesitate - to call it more often for safety; if the sound stutters, you may need to - do just that. (Or you may need to increase the buffer size or reduce the - quality settings; the only way to find out is to try.) - - For now, don't worry about al_poll_duh()'s return value. As soon as you - need it, it will be explained. - - If you are happy, please skip to Step 9. If you were expecting DUMB to - play your music in the background, please read on. - - The natural way to play music in the background on most operating systems - nowadays is to use threads. DOS was not built with multithreading in mind, - and its system operations (notably disk access) assume they will only be - used from a single thread. - - Interrupts are the next best thing to threads. A DOS hardware interrupt - could be triggered at any moment, and a handler function will be called. - This is how Allegro's timer functions work. Unfortunately, what you can do - inside an interrupt handler is very limited. For one thing, all code and - data used by the handler must be locked in memory; if not, it could get - written to disk (virtual memory). If the main program was accessing the - disk when it got interrupted, the system would then die a horrible death. - This precludes the possibility of allocating extra memory inside the - handler, and DUMB does a lot of that in al_poll_duh(). - - Given DUMB's architecture, which cannot change for reasons which will - become apparent in future versions, this renders it impossible to come up - with a portable solution for making DUMB play music in the background. - Having said that, if you wish to write your own wrapper for al_poll_duh() - and use it in a thread, there is nothing stopping you. If you do do this, - you will have to be very careful when stopping the music; see the - description of al_poll_duh() in dumb.txt for more information. - - So why not remove DOS support from DUMB? It is all too common a practice - among programmers to quote the phrase, "DOS is as dead as the dodo." - Despite being a decidedly derisible demonstation of the dreary device of - alliteration, it shows a distinct lack of experience. Many embedded - systems still use DOS because it provides hardware access capabilities and - real-time possibilities unparalleled by any current multitasking operating - system. For an argument closer to home, I used to use RHIDE for DOS before - I switched to Linux, and I have not found a single Freeware Windows IDE - that measures up to RHIDE. I'm sure many people are in the same boat, and - really appreciate DUMB's DOS port. - - That, and the fact that you don't have to use the DOS support just because - it is there. Shame on you for not thinking this through. :) - - We will not be removing DOS support from DUMB. Any blind suggestions to do - so will be met with fiery flames. You have been warned. - - -9. Test your program! - - If you have trouble, check through the above steps to make sure you didn't - miss one out. Refer to faq.txt to see if your problem is addressed there. - If you still have trouble, contact me; details are at the end of this - file. - - -********************************** -*** Controlling music playback *** -********************************** - - -Here I describe some common operations you may wish to perform. The method -for doing so will seem a bit strange sometimes, as will the names of the -structs. However, there is a reason behind everything. If you would like to -do more exotic things, or better understand some of the methods used here, -then see dumb.txt, which covers everything from the ground up. - - -To control playback quality: - - #define DUMB_RQ_ALIASING - #define DUMB_RQ_LINEAR - #define DUMB_RQ_CUBIC - #define DUMB_RQ_N_LEVELS - extern int dumb_resampling_quality; - extern int dumb_it_max_to_mix; - - Please note that dumb_resampling_quality was changed in DUMB v0.9.2. See - deprec.txt for more details on the change. - - dumb_resampling_quality can be set to any of the DUMB_RQ_* constants - (except DUMB_RQ_N_LEVELS; see below). Resampling is the term given to the - process of adjusting a sample's pitch (in this context). - dumb_resampling_quality defaults to DUMB_RQ_CUBIC, which sounds nice but - may take too much processor power on slower systems. Try reducing it if - you have an older computer (less than 300 MHz) or if you are trying to mix - an insane number of samples (or both!). See dumb.txt for details on what - the different values actually do. - - If you wish to give this option to your user, you can use - DUMB_RQ_N_LEVELS. All the values from 0 to DUMB_RQ_N_LEVELS - 1 will be - valid resampling levels. If a value outside this range is chosen, it is - not the end of the world; DUMB will behave as if you had chosen the value - at whichever extreme you went beyond. - - dumb_it_max_to_mix, defaulting to 64, is the maximum number of samples - DUMB will ever mix together when playing an IT, XM, S3M or MOD file. - Unlike many other music systems, DUMB will still keep track of all samples - (up to a fixed maximum of 256 of them, roughly speaking), and then will - just render as many of them as this variable permits, starting with the - loudest ones. When samples are cut or come back in, the exact timings will - not generally be predictable - but it is hoped this will not be important! - - dumb_it_max_to_mix applies to each currently playing module file - independently. So if you set it to 64, but render two modules - simultaneously, DUMB could end up mixing up to 128 samples. - - -To pause and resume playback, set the volume, get the current playback -position, or get the length of time a DUH will play for before either looping -or freezing (effect F00 in XM and MOD files, which means no new notes will be -played but any existing notes will continue): - - void al_pause_duh(AL_DUH_PLAYER *dp); - void al_resume_duh(AL_DUH_PLAYER *dp); - void al_duh_set_volume(AL_DUH_PLAYER *dp, float volume); - long al_duh_get_position(AL_DUH_PLAYER *dp); - - long duh_get_length(DUH *duh); - - These functions are pretty self-explanatory. The volume passed to - al_duh_set_volume() and the position returned by al_duh_get_position() are - in the same units as those you passed to al_start_duh(). Be careful with - al_duh_get_position(); it will return a position slightly ahead of what - you can hear, because the system has to keep ahead slightly to avoid - stuttering. - - duh_get_length() returns the playback length, in the same units as the - aforementioned position, but beware: the length will not be known if you - have used the "quick" loader functions, and this function will return -1. - If you want to calculate the length later, use - dumb_it_do_initial_runthrough(). See dumb.txt for more information. - - -To prevent the music from looping and/or freezing: - - DUH_SIGRENDERER *al_duh_get_sigrenderer(AL_DUH_PLAYER *dp); - DUMB_IT_SIGRENDERER *duh_get_it_sigrenderer(DUH_SIGRENDERER *sigrenderer); - - void dumb_it_set_loop_callback(DUMB_IT_SIGRENDERER *sigrenderer, - int (*callback)(void *data), void *data); - void dumb_it_set_xm_speed_zero_callback(DUMB_IT_SIGRENDERER *sigrenderer, - int (*callback)(void *data), void *data); - - int dumb_it_callback_terminate(void *data); - - If you are unfamiliar with function pointers, please see fnptr.txt. - - Note that these functions apply to IT, XM, S3M and MOD files - not just to - IT files. This holds true throughout DUMB, for all functions with "it" in - the name. The xm_speed_zero event can only occur with XM and MOD files. - - The first two functions will return a pointer to a struct contained by the - struct you pass. This system is necessary to ensure that these operations - are possible when not using Allegro. Typically you would write the - following code: - - { - DUH_SIGRENDERER *sr = al_duh_get_sigrenderer(dp); - DUMB_IT_SIGRENDERER *itsr = duh_get_it_sigrenderer(sigrenderer); - dumb_it_set_loop_callback(itsr, &dumb_it_callback_terminate, NULL); - dumb_it_set_xm_speed_zero_callback - (itsr, &dumb_it_callback_terminate, NULL); - } - - Once you have done this, the return value of al_poll_duh() becomes - significant. It will be 0 as long as the music is playing. When the music - stops, al_poll_duh() will return nonzero. You can call al_stop_duh() and - do something else as soon as you wish, but calling al_poll_duh() some more - will not do any harm. - - al_poll_duh() will also return 1 if the music could not be loaded, or if - memory was short when trying to play it, or if it was a quirky music file - with no music in it (technically one with an empty order list). This - happens regardless of whether or not you execute the above code to disable - looping. Normally you shouldn't need to worry about this. - - To undo the above and make DUMB loop or freeze again, pass NULL instead of - &dumb_it_callback_terminate. If you would like to fade on looping, or loop - a finite number of times, or display a message when looping, or whatever, - you will have to write your own callback function. In this case, please - see dumb.txt. - - Note that the above code can safely be applied for a DUH that doesn't - contain a music module but contains some other kind of music. - duh_get_it_sigrenderer() will return NULL, and the code will do nothing. - - -To analyse the audio as it is generated: - - typedef int sample_t; - - typedef void (*DUH_SIGRENDERER_SAMPLE_ANALYSER_CALLBACK)(void *data, - const sample_t *const *samples, int n_channels, long length); - - void duh_sigrenderer_set_sample_analyser_callback( - DUH_SIGRENDERER *sigrenderer, - DUH_SIGRENDERER_SAMPLE_ANALYSER_CALLBACK callback, void *data); - - If the above confuses you, see fnptr.txt. These functions, along with - al_duh_get_sigrenderer() from the last section, enable you to register a - callback function. Every time some samples are generated, they will be - passed to this function. This enables you to display an oscilloscope or - spectrum analyser, for example. - - Beware: your callback function may occasionally be called with - samples == NULL. This means the main program has decided to skip through - the music without generating any data. You should handle this case - elegantly, typically by returning immediately, but you may wish to make a - note of the fact that the music is being skipped, for whatever reason. - - Beware again: if the main program ever calls - duh_sigrenderer_generate_samples() on a buffer that isn't all silence, - this callback function will be passed the existing buffer after mixing, - and thus it will include the original data. This will not be an issue if - you stick to duh_render(), which always starts with a buffer filled with - silence. - - The samples array is two-dimensional, but the first index will always be 0 - for mono and stereo sound. Refer to it as follows: - - n_channels == 1: samples[0][sample_position] - n_channels == 2: samples[0][sample_position*2+channel_number] - - where 0 <= channel_number < n_channels, - and 0 <= sample_position < length. - - There is a more thorough explanation in dumb.txt. - - In addition you can pass any 'data' pointer you like to - duh_sigrenderer_set_sample_analyser_callback(), and this pointer will be - relayed to your callback function each time. - - To remove the callback function, pass NULL to - duh_sigrenderer_set_sample_analyser_callback(). - - -Everything below this point assumes some knowledge of how a music module is -constructed. If you do not have this knowledge, talk to whoever is writing -music for you, or download a tracking program and play with it (see -readme.txt). - - -To start playing an IT, XM, S3M or MOD from an arbitrary order number (the -default being 0, the beginning of the song), use the following: - - DUH_SIGRENDERER *dumb_it_start_at_order - (DUH *duh, int n_channels, int startorder); - AL_DUH_PLAYER *al_duh_encapsulate_sigrenderer - (DUH_SIGRENDERER *sigrenderer, float volume, long bufsize, int freq); - - The usage of these functions is as follows: - - { - DUH_SIGRENDERER *sr = dumb_it_start_at_order - (duh, n_channels, startorder); - dp = al_duh_encapsulate_sigrenderer(sr, volume, bufsize, freq); - if (!dp) duh_end_sigrenderer(sr); - } - - Replace 'dp' with whatever your AL_DUH_PLAYER pointer is. You also need - to insert suitable values for n_channels, startorder, volume, bufsize and - freq. These have the same meaning as those passed to al_start_duh(). - - Whenever you call al_duh_encapsulate_sigrenderer(), be sure to check the - return value. If an AL_DUH_PLAYER was returned, then the encapsulated - DUH_SIGRENDERER will be destroyed when you destroy the AL_DUH_PLAYER. If - not, you will have to destroy the DUH_SIGRENDERER yourself. The above code - includes this check. - - The above functions will fail (safely) if you try to use them with a DUH - that contains a different type of music. No music will play. - - Notice that there is no 'pos' parameter. If you would like to skip through - the music, you can use this function: - - long duh_sigrenderer_generate_samples( - DUH_SIGRENDERER *sigrenderer, - float volume, float delta, - long size, sample_t **samples - ); - - Pass 0 for volume and NULL for samples, and this function will skip - through the music nice and quickly. So insert the following between the - two above statements: - - duh_sigrenderer_generate_samples(sr, 0, 65536.0f / freq, pos, NULL); - - Substitute for 'freq' and 'pos'. An explanation of the 'delta' parameter - can be found further down in this file. - - Finally, note that duh_get_length() is only meaningful when you start - playing music from order 0. - - -If an IT file contains Zxx effects, DUMB will generate MIDI messages, which -will control the low-pass resonant filters unless the IT file actively -specifies something else. In rare cases this may not be what the Zxx effects -were intended to do; if this is the case, you can block the MIDI messages as -follows. Note that this does NOT mean filters are disabled; if an instrument -specifies initial cut-off and resonance values, or has a filter envelope, -then filters will be applied. It only makes sense to use this procedure at -the beginning of playback. - - void dumb_it_set_midi_callback(DUMB_IT_SIGRENDERER *sigrenderer, - int (*callback)(void *data, int channel, unsigned char byte), - void *data); - - int dumb_it_callback_midi_block(void *data, int channel, - unsigned char byte); - - Using some functions described in the previous section, we arrive at the - following code: - - { - DUH_SIGRENDERER *sr = al_duh_get_sigrenderer(dp); - DUMB_IT_SIGRENDERER *itsr = duh_get_it_sigrenderer(sigrenderer); - dumb_it_set_midi_callback(itsr, &dumb_it_callback_midi_block, NULL); - } - -DUMB offers no way of disabling filters completely. Disabling filters is not -recommended as a means to reduce processor usage, as it will completely -damage any piece of music that uses the filters. If you want lower processor -consumption, use a piece of music that does not use filters. - - -Finally, DUMB offers a myriad of functions for querying and adjusting -module playback. Those beginning with "dumb_it_sd" operate on the -DUMB_IT_SIGDATA struct, which represents the piece of music before it starts -to play. Those beginning with "dumb_it_sr" operate on the DUMB_IT_SIGRENDERER -struct, which represents a currently playing instance of the music. Note that -duh_get_length(), described above, becomes meaningless after some of these -functions are used, although you can correct this by calling -dumb_it_build_checkpoints() again. - -The method for getting a DUMB_IT_SIGRENDERER struct has already been given, -but the function prototypes are repeated here for convenience: - - DUH_SIGRENDERER *al_duh_get_sigrenderer(AL_DUH_PLAYER *dp); - DUMB_IT_SIGRENDERER *duh_get_it_sigrenderer(DUH_SIGRENDERER *sigrenderer); - -Getting a DUMB_IT_SIGDATA struct is simpler: - - DUMB_IT_SIGDATA *duh_get_it_sigdata(DUH *duh); - -For a list of dumb_it_sd_*() and dumb_it_sr_*() functions, please see -dumb.txt. These functions are new, and may not provide exactly what you need; -if not, please let me know. - - -************************************************** -*** Embedding music files in Allegro datafiles *** -************************************************** - - -In this section it is assumed you are already reasonably familiar with how -Allegro datafiles are used. If not, please refer to Allegro's documentation. -At the time of writing, the documentation you need is off the beaten track, -so to speak, in allegro/tools/grabber.txt. - -To add a piece of music to a datafile, you need to create an object of type -"IT ", "XM ", "S3M " or "MOD " (note the spaces used as padding, although -you do not need to type these into the grabber). Then grab the piece of music -in. The grabber will treat it as a binary object. Save the datafile as usual. - - -To use a piece of music you added to the datafile, follow these steps: - - -1. Before loading the datafile, call one or more of these functions, - depending on which music format or formats you'd like to support: - - dumb_register_dat_it_quick(DUMB_DAT_IT); - dumb_register_dat_xm_quick(DUMB_DAT_XM); - dumb_register_dat_s3m_quick(DUMB_DAT_S3M); - dumb_register_dat_mod_quick(DUMB_DAT_MOD); - - There are non-"quick" versions too. - - Remember, do not call multiple functions unless you want to support - multiple formats. Calling more functions will add unused code to your - executable. - - It is important that you call these before loading the datafile, since - they tell Allegro how to load the respective files straight from datafiles - in the future. They will not help Allegro interpret any module files that - have already been loaded as binary objects. If you ever need to interpret - a module that has been loaded in this fashion, have a look at - dumbfile_open_memory() in dumb.txt. - - If for whatever reason your music objects are identified by a different - type in the datafile, you can tell DUMB what that type is by changing the - parameter to the registration function above. Use Allegro's DAT_ID() - macro, e.g. DAT_ID('B','L','A','H'). This is not really recommended - though, since it would prevent a hypothetical grabber plug-in from being - able to play your music files. Use the above types if possible. - - -2. Whenever you need a pointer to a DUH struct, simply use the 'dat' field. - Do this in the same way you would for a pointer to a BITMAP struct or - anything else. If it makes you feel more comfortable, you can extract the - pointer in advance: - - DATAFILE *dat = load_datafile("smurf.dat"); - if (!dat) abort(); /* There are much nicer ways of handling failure! */ - DUH *myduh = (DUH *)dat[GAME_MUSIC].dat; - - The explicit (DUH *) cast is only necessary for C++, not for C. However, - it does no harm. - - Be sure that you do NOT call unload_duh() for anything stored in the - datafile. These DUHs will be freed when you call unload_datafile(), and - freeing them twice is practically guaranteed to crash your program. (But - do call unload_duh() if you have used dumbfile_open_memory().) - - -3. If you only ever load music as part of a datafile, and you never load any - stand-alone music files, you do not need to register a file input system - for DUMB to use. If you followed the instructions for the first section - you will have one of these two lines in your program: - - dumb_register_stdfiles(); - dumb_register_packfiles(); - - You can safely delete this line - but only if you never load any - stand-alone music files. The debugging library will bale you out if you - delete it when you shouldn't; the optimised library won't. - - -************************************* -*** Rendering music into a buffer *** -************************************* - - -NOTE: much of the API formerly described in this section has been deprecated, - and you will need to alter your code. See deprec.txt for details. If - you are reading this section for the first time, you can ignore this - note. - -Rendering to a buffer is similar to playing using an AL_DUH_PLAYER. However, -you must use a DUH_SIGRENDERER struct instead. Here are the functions: - - DUH_SIGRENDERER *duh_start_sigrenderer - (DUH *duh, int sig, int n_channels, long pos); - - int duh_sigrenderer_get_n_channels(DUH_SIGRENDERER *sigrenderer); - long duh_sigrenderer_get_position(DUH_SIGRENDERER *sigrenderer); - - long duh_sigrenderer_generate_samples(DUH_SIGRENDERER *sigrenderer, - float volume, float delta, long size, sample_t **samples); - - void duh_sigrenderer_get_current_sample(DUH_SIGRENDERER *sigrenderer, - float volume, sample_t *samples); - - long duh_render(DUH_SIGRENDERER *sigrenderer, - int bits, int unsign, float volume, float delta, long size, void *sptr); - - void duh_end_sigrenderer(DUH_SIGRENDERER *sigrenderer); - -The parameters to duh_start_sigrenderer() have the same meanings as those to -al_start_duh(). However, note that the volume is not set at this stage. You -pass the desired volume each time you want to render a block. The 'sig' -parameter should be set to 0 for now. - -Notice that there are two rendering functions. -duh_sigrenderer_generate_samples() will generate samples in the internal -32-bit format, with a normal range from -0x800000 to 0x7FFFFF; duh_render() -will convert to 8 or 16 bits, signed or unsigned. Both functions will -interleave stereo samples, left first. - -When you call duh_render(), pass 8 or 16 for 'bits'. If you pass 8, 'sptr' is -expected to be an array of chars. If you pass 16, 'sptr' is expected to be an -array of shorts. Endianness therefore depends on the platform, and you should -not try to interpret 16-bit wave data as an array of chars (unless you're -writing highly system-specific code anyway). Because DUMB renders internally -with 32 bits, there is no significant speed increase in rendering an 8-bit -stream. - -If you are rendering in stereo, make sure your 'sptr' array is twice as big! - -If you set 'unsign' to a nonzero value, then the samples generated will be -centred on 0x80 or 0x8000, suitably stored in an array of unsigned chars or -unsigned shorts. If 'unsign' is zero, the samples will be centred on 0, -suitably stored in an array of signed chars or signed shorts. Note that 8-bit -WAV files are unsigned while 16-bit WAV files are signed. This convention was -used by the SoundBlaster 16 when receiving samples to be sent to the -speakers. If you wish to write 16-bit sample data to a WAV file, don't use -fwrite(); instead, take the shorts one at a time, split them up into chars as -follows, and write the chars to the file. - - short sptr[n]; - char lsb = (char)sptr[n]; - char msb = (char)(sptr[n] >> 8); - -For a 16-bit WAV file, write the LSB (less significant byte) first. - -The following applies equally to duh_render() and -duh_sigrenderer_generate_samples(), except where otherwise stated. - -If you set 'delta' to 1.0f, the sound generated will be suitable for playback -at 65536 Hz. Increasing 'delta' causes the wave to speed up, given a constant -sampling rate for playback. Supposing you want to vary the playback sampling -rate but keep the pitch constant, here's the equation for 'delta': - - delta = 65536.0f / sampling_rate; - -'size' is the number of samples you want rendered. For duh_render(), they -will be rendered into an array which you pass as 'sptr'. Note that stereo -samples count as one; so if you set n_channels to 2, your array must contain -(2 * size) elements. - -For duh_sigrenderer_generate_samples() you will have to use the following -functions: - - sample_t **allocate_sample_buffer(int n_channels, long length); - void destroy_sample_buffer(sample_t **samples); - - void dumb_silence(sample_t *samples, long length); - -allocate_sample_buffer() allocates the buffers sequentially in memory in the -hypothetical future case where there are more than two channels, so the -following technique is valid and officially supported: - - sample_t **samples = allocate_sample_buffer(n_channels, length); - dumb_silence(samples[0], n_channels * length); - -It is necessary to fill the buffer with silence like this because -duh_sigrenderer_generate_samples() mixes what it renders with the existing -contents of the buffer. - -The return values from duh_render() and duh_sigrenderer_generate_samples() -tell you how many samples were actually generated. In most cases, this will -be the same as the 'size' parameter. However, if you reach the end of the DUH -(which will happen if you disable looping or freezing as described further -up), this function will return less. When that happens, you can assume the -stream has finished. In the case of duh_render(), the remainder of the array -will not have been initialised, so you either have to initialise it yourself -or avoid using it. - -If for whatever reason duh_start_sigrenderer() returns NULL, then -duh_render() and duh_sigrenderer_generate_samples() will generate exactly 0 -samples, duh_sigrenderer_get_n_channels() will return 0, -duh_sigrenderer_get_position() will return -1, and duh_end_sigrenderer() will -safely do nothing. - -duh_sigrenderer_get_current_sample() is used by the click removal algorithm. -It simply returns the current sample without updating the position, so you -can use it to sniff what is coming next. - - -********************* -*** Miscellaneous *** -********************* - - -Please see dumb.txt for an API reference and for information on thread safety -with DUMB. The API reference has been stripped down, since some functions and -variables are subject to change. If something does not appear in dumb.txt, -please do not use it. - - -****************** -*** Conclusion *** -****************** - - -If you have any difficulties, or if you use DUMB successfully, please don't -hesitate to contact me (see below). - -Enjoy! - - -Ben Davis -entheh@users.sf.net |