Audio 4.94 - Over 11,000 Files

home *** CD-ROM | disk | FTP | other *** search

/ Audio 4.94 - Over 11,000 Files / audio-11000.iso / amiga / players / modplyrs / dstrckr2.lha / DTL / docs / Structures.DOC < prev

Wrap

Text File | 1993-12-17 | 42KB | 1,067 lines

destracker.library Release 2.00 (library ver 3.0) Documentation as of Dec 18, 1993 Written by Darren Schebek destracker.library, LScope, DTC, mJuke,and MODInfo are all Designed and written by Darren Schebek Copyright ⌐1992,1993 by Darren Schebek All rights reserved Library Structures Documentation -------------------------------- This file contains documentation regarding the custom structures used by destracker.library. All instances of these structures created by the library can be accessed via the library base structure. Like any other amiga library, you get a pointer to the library base structure when you open the library. The library base structure itself is also documented here. All of these structures are defined in the file DTLib.I (as well as its C counterpart, dtlib.h). C users can disregard any references to "LABEL" fields, as these are only required for assembly language (they are equates for the size of a structure, e.g. "LABEL pe_SIZE" = "sizeof(struct PATHENTRY);" in C). Please note that new fields have been added to some of these structures for version 3.0 of the library. They are noted as such. ----------------------------------------------- The MODULESTATUS Structure The MODULESTATUS structure contains information which is specific to a given song module. The fields of this structure are valid only while a song module is currently loaded. If no module is loaded, their contents are unpredictable and consequently useless. You can look at the DTLibs.I file to see the definition of the MODULESTATUS structure (or DTLib.h), so I'll just describe each field here in the order that they appear in the structure definition. Note that, as of release 1.5 of DES-Tracker, two new fields have been appended to this structure (ms_Pathname and ms_Filename). As a result, those of you who'd like to update to release 1.5 (and future releases) of DES-Tracker will have to recompile any programs that use older versions of DES-Tracker using the new DTLib.I file included in this package. Sorry for the inconvenience. Also, three new fields have been added to this structure for release 2.00 of DES-Tracker (library version 3.0). They are appended to the end and are indicated as being new in the descriptions below. APTR ms_Name The ms_Name field is a pointer to a NULL-terminated string of text. The text in this case is the title of the song, extracted from the module file when it was loaded. Because of the rather deranged concepts used in the design of the Noisetracker/Soundtracker file formats, this name will only ever be a maximum of 20 characters long (for now. With the advent of support for newer formats, this limitation may be eradicated, so don't assume that the name string will always be 20 chars long). This length does not include the terminating NULL at the end of the string. ULONG ms_Length (Contents altered slightly as of lib v3.0) This longword field contains the length of the module in memory. Note that the song as it sits in memory has been converted from whatever file format it was in when it was loaded to DES-Tracker v1.0 format. Therefore, the length indicated here is the length of the song module if you were to save it out in DES-Tracker v1.0 file format. You may notice that this length is almost always shorter than the length of the file in Noisetracker, Protracker, or Soundtracker format. It's quite efficient. APTR ms_PlaySeqArray (New field for release 2.00, lib v3.0) This field holds a pointer to the currently loaded song module's play sequence array. The array is composed of double-longword elements. Each element consists of four words. Each word is a pattern number to play; one for each audio channel. The array is indexed with the current song position and so there are "numpositions" elements in the array. APTR ms_PatternData (New field for release 2.00, lib v3.0) This field holds a pointer to the currently loaded song module's pattern data. A pattern is an array of 64 longwords. Each longword is a note event that is to be processed for a single, arbitrary audio channel. All patterns reside in memory contiguously. The "ms_PatternData" field points to the first element of pattern #0. 256 bytes beyond this point lies the first element of pattern #1, then pattern #2, etc. APTR ms_InstInfoBlocks (New field for release 2.00, lib v3.0) This points to 31 instrument info blocks as extracted (verbatim) from the song module file itself. Each instrument info block is 30 bytes in size and looks like this: char[22] Name of the instrument. UWORD Length of instrument's sample data in words. BYTE Fine tune value for this instrument (-8..+7). UBYTE Default volume for this instrument (0..64). UWORD Offset to repeat start position for inst sample in words. UWORD Length of the instrument sample's repeat loop in words. This pointer is useful if you require access to all instrument info blocks in the song module, rather than just those that actually have instrument samples associated with them (which is what ms_Instruments gives you). UBYTE ms_Format This byte field contains a value reflecting what file format a module on disk was when it was loaded, regardless of the fact that it is converted to DES-Tracker v1.0 format once it's loaded into memory. If the module was in Soundtracker v2.6 format, then this field will contain MF_SOUNDTRACKER. If the module was in either Noisetracker v2.0 or Protracker v1.1a and up, then this field will contain MF_NOISETRACKER (Noisetracker and Protracker file formats are identical). If the file loaded was in DES-Tracker v1.0 ("DTL0") format, then this field will contain MF_DESTRACKER. These labels are defined in DTLib.I and DTLib.H. UBYTE ms_Version This field contains the version number of the format of the module that was loaded. For example, if the module was in Noisetracker v2.0 format, then this field will contain the value 2 (the number to the left of the decimal point). UBYTE ms_Revision This field contains the revision number of the format of the module that was loaded. For Noisetracker v2.0, this field contains 0. For Soundtracker v2.6 format, this field will contain 6. UBYTE ms_Reserved This field is reserved and should always contain 0. APTR ms_Instruments This is a pointer to the first INSTSTATUS structure in a linked list. This list contains one INSTSTATUS structure for each instrument used in a module. It does NOT contain 31 INSTSTATUS structures. If a module only uses three of the 31 possible instrument slots, then there will only be three INSTSTATUS structures in this list. See the explanation a bit further down from here for the INSTSTATUS structure fields. UWORD ms_NumPatterns This field contains the number of unique patterns comprising the module. In this context, a "pattern" is made up of 256 bytes that describe 64 notes to be played in a single arbitrary audio channel. This value can be greater than 256. If it is, then the song module in memory cannot be saved out in Soundtracker v2.6 format, since that format can only handle up to 256 unique patterns. However, DES-Tracker v1.0 supports 65,535 patterns, so the module can be saved in that format. Song modules can always be saved in Noisetracker/Protracker format. UWORD ms_NumPositions This contains the number of positions in the song, which would be analogous to the number of measures in real musical notation. When playing a module, play normally begins at position 0 and ends at this position, whereby the module either stops or repeats (although with this library you can start and stop play at any point in a module). APTR ms_Pathname (New field as of release 1.5) This is a pointer to the path specification from which the currently loaded module was loaded from. It is a NULL-terminated string. If you call the SaveModule() function with no parameters, then the path specified here will be used to save the module in memory. Also, if you call SaveModule() with a different path/filename, then this field will then point to the new path afterwards. This is a new field in the MODULESTATUS structure as of release 1.5 of DES-Tracker. APTR ms_Filename (New field as of release 1.5) This is a pointer to the filename of the currently loaded module. If you call SaveModule() with no parameters, then the filename used will be the one pointed to by this field. Calling SaveModule() with a new filename will cause this field to point to the new filename after the save operation is completed. This is a new field in the MODULESTATUS structure as of release 1.5 of DES-Tracker. LABEL ms_SIZE This is merely an equate. ms_SIZE is equated to the size of the MODULESTATUS structure. ----------------------------------------------- The INSTSTATUS Structure The INSTSTATUS structure contains information for a single instrument used by a module. When a module is loaded, a linked list of these INSTSTATUS structures is created, with one INSTSTATUS structure for each instrument slot that is actually used by the module (see MODULESTATUS structure docs above). Like the MODULESTATUS structure, the contents of an INSTSTATUS structure are only valid while a module is loaded. Here is an explanation of each field in the INSTSTATUS structure. APTR is_Next This is a pointer to the next INSTSTATUS structure in the linked list. If this is the last structure in the list, then this field will contain NULL. APTR is_Name This field contains a pointer to the name of the instrument as a NULL-terminated text string. It bothers me to no end when people write messages over top of the instrument names (Grrrr!). At least they could use empty instrument slots for this, but NOoooooo. :) Oh well. APTR is_Address This field contains a pointer to the actual instrument raw sample data. ULONG is_Length The length of the raw instrument sample data is stored here. The length stored here is the length of the sample data in BYTES, NOT words. Keep this in mind. ULONG is_Repeat This field contains the offset in BYTES from the beginning of the instrument sample data to the start of the repeat portion of the instrument. ULONG is_RepeatLen This field contains the length of the repeat portion of the instrument sample data in BYTES. UBYTE is_Number This field contains the number of the slot used by this instrument. There are 31 possible slots available for use in a module file. Slots are numbered starting at 1 and going up to and including 31. Although unused slots are ignored when building the INSTSTATUS structure list, each instruments slot number remains pristine. BYTE is_FineTune This field holds the fine tune amount for the instrument. It is almost always 0, partly because most people who sample instruments do things right, but mostly because this field is only supported by the Protracker editor. The range of the fine tune value is -8..7 inclusive. Fine tune can also be used for precision synching of special looping samples that are to be timed with the music (e.g. a single sample of a complete drum beat that must be timed perfectly with the rest of the music. Since percussion instruments have no discernable pitch per se, altering their pitch with the fine tune value does not typically affect the sound of the drums in a bad way). UBYTE is_Volume This byte field contains the default volume of the instrument. This is a value from 0..64 inclusive. 0 is silent, and 64 is maximum volume. UBYTE is_Reserved This is a reserved field and should always be set to 0. LABEL is_SIZE This is an equate. It is defined as the size of the INSTSTATUS structure. ----------------------------------------------- The CHANNELSTATUS Structure The CHANNELSTATUS structure contains real-time information about a single audio channel. The information in a CHANNELSTATUS structure is only valid when a loaded module is playing. If the module is not playing (or if no module is loaded) then the information in this structure is invalid. Here is a rundown of the fields in the CHANNELSTATUS structure. UBYTE cs_Note This field contains the last note played in the audio channel in the form of a value from 0..35 inclusive. 0 is the lowest pitch and 35 is the highest pitch. UBYTE cs_Octave This holds the octave number of the last note played, which is a value from 0..2 inclusive. 0 is the lowest octave. This value is derived from the cs_Note field by dividing its contents by 12. This value is provided for your convenience. UBYTE cs_NoteNum This holds the number of the last note played relative to the octave in which it is played. It is a value from 0..11 inclusive. This value is derived from the contents of cs_Note by taking the remainder of (cs_Note/12). This field, like cs_Octave above, is provided for your convenience. UBYTE cs_Volume This field contains the current volume of the audio channel, which is a value from 0..64 inclusive. Note that any adjustment of the global volume (see SetGlobalVolume function in LibFuncs.DOC) will not be reflected here, even though reducing global volume causes you to *hear* a reduction in global volume. This value is always updated whenever the volume of the channel is altered (not just when a note is first played, like the fields above). UBYTE cs_RealVolume (New field for release 2.00, lib v3.0) This field contains the current volume of the audio channel with global volume applied to it. It is updated whenever the channel volume changes and also whenever the global volume is changed. Its range is 0..64 inclusive. UBYTE cs_Pad (New field for release 2.00, lib v3.0) This is a reserved field and always contains zero. Not terribly useful or even interesting, really. :) UWORD cs_Period The period of the note in the current channel is stored here, and is updated whenever the period of the channel is changed (not just when a note is first played). This means that you can get accurate period status on an audio channel through pitch bends and slides. APTR cs_Instrument This field contains a pointer to the INSTSTATUS structure of the instrument last used in this audio channel. Using this field you can get all sorts of info on an instrument as soon as it is used, whenever it is used. ULONG cs_SampleOffset (New field for release 2.00, lib v3.0) Whenever a new note hit occurs in an audio channel, it may use the "Sample Offset" command. This causes the instrument's sample to start playing from a position other than the beginning of the sample. If this happens then the "cs_SampleOffset" field here will contain the offset from the beginning of the instrument's sample data that was used. LABEL cs_SIZE This is an equate. It is defined as the size of the CHANNELSTATUS structure. ----------------------------------------------- The PATHENTRY Structure As of release 1.5, DES-Tracker can now remember multiple search paths to be used by the LoadModule() function when it is looking for a specified module to load. These search paths are kept in a linked list (see the 'dtl_ModPathList' field of the library base structure). Each search path in the linked list is stored as a PATHENTRY structure, since PATHENTRY structures can be linked together (whereas text strings can't). The structure contains only two fields. The actual text string that is the search path begins immediately after the pe_Length field. The string itself is always NULL-terminated. APTR pe_Next This is the field that allows PATHENTRY structures to be linked together. the contents of this field is a pointer to the next PATHENTRY structure in the linked list, or else it contains NULL (0) meaning that this is the last PATHENTRY in the list. UWORD pe_Length This field contains the length of the text string immediately following this field. The length includes the string's terminating NULL character. This length value does NOT include the size of the PATHENTRY structure - only the text string appended to it. LABEL pe_SIZE This is an equate defined as the size of the PATHENTRY structure (NOT including the pathname string appended to it). ----------------------------------------------- The TIMESCANINFO Structure (New structure for release 2.00, lib v3.0) This structure is used in conjunction with the CalcElapsedTime() function. You fill out a TIMESCANINFO structure and pass a pointer to it to the CalcElapsedTime() function. The function, in turn, will fill out a couple of fields in the structure for you (i.e., the calculated elapsed time for playing the song). Note that the Start Position/Note must always be "less" than the End Position/Note (by "less" I mean that the start point must be earlier in the song than the end point, even if it's only by a single note). Anyway, here's a description of the individual fields. UBYTE tsi_StartPos CalcElapsedTime() requires a start point and an end point for its calculations. You store the position number of the start point here. This value ranges from 0..ms_NumPositions-1 (see MODULESTATUS structure above). UBYTE tsi_StartNote Here you store the note number within the start position. This is a value from 0..63 inclusive. A value of 0 means the first note of the start position, 1 means the second note, etc. UBYTE tsi_EndPos You store the position number of the end point here. This field follows the same rules as tsi_StartPos above. UBYTE tsi_EndNote You store the note number within the end position here. Like tsi_StartNote, this is a value from 0..64. UBYTE tsi_Flags This field contains three flags. They are as follows: Bit 0 TSIB_MULTIPLEITERS It takes time to calculate the time it will take to play a song for one iteration. It then goes without saying that it will take even longer to calculate the time for two iterations. But in many songs, iterations after the first one can take less time (because the song may loop back to a position other than the beginning of the song). This flag tells CalcElapsedTime() whether to calculate elapsed time for just one iteration, or to calculate the time for an extra iteration as well (all iterations after the first one take the same time). By setting this bit, CalcElapsedTime() will calculate an extra iteration for you. Bit 1 TSIB_TEMPOINTERP This flag tells CalcElapsedTime how to interpret tempo commands it may come across while scanning the music. If this bit is clear (0), then the operand for a tempo command will be interpreted as such: Operand Interpretation 0..31 Normal tempo command 32..255 Set BPM tempo command If the bit is set to 1, then all tempo command operands are treated as normal tempos (i.e., BPM tempos no longer occur - all values for the tempo command operand are treated as normal tempo values). Bit 2 TSIB_TIMINGMODE This flag indicates the initial base timing for the scan. If this bit is clear, then the initial base timing will be 60Hz. If it is set, then the initial base timing will be 50Hz. UBYTE tsi_DefaultTempo Here you store the default (initial) tempo of the song for the music scan. This is the same type of value as contained in the dtl_DefaultTempo field in the library base structure (described below). UBYTE tsi_FineTempo You store the desired fine tempo setting for the music scan here. This is a signed value in the range -128..+127. Each fine tempo unit represents a change in the overall tempo of the song by 0.078125Hz. So, a value of +30 would increase the overall tempo of the song by (30 * 0.078125Hz) = +2.34Hz. In the extremes, a value of +127 increases the tempo by +10Hz, and -128 Slows down the tempo by 10Hz. UBYTE tsi_Pad This is a reserved field and should always contain 0. ULONG tsi_FirstIterTime This field is filled out for you by the CalcElapsedTime() function. It holds the calculated play time for the first iteration of the play sequence described by the TIMESCANINFO structure parameters. This play time value is in units of 60ths of a second. ULONG tsi_ConsecIterTime If you set the TSIB_MULTIPLEITERS flag in the tsi_Flags field, then this field will contain the play time for consecutive iterations of the song (i.e., iterations of the song after the song plays through once). This value is also in 60ths of a second. If you want to know the total play time of a song for n iterations, then the formula is as follows: TotalTime = tsi_FirstIterTime + (tsi_ConsecIterTime * (n-1)) The result (TotalTime) is of course in units of 60ths of a second. ----------------------------------------------- The LIBRARY BASE Structure DES-Tracker's library base structure contains a plethora of information about not only a loaded module, but also real-time play status info, as well as current settings of all library parameters. You do not need to own the library to read the info in the library base structure, and you can read this structure even if someone else has owned the library. It is important to note that ALL fields in the library base structure are READ ONLY. Do not write values to any fields in this structure. Use the library routines. It is also advisable that you own the library as soon as you open it (provided someone else has not already done so) using the OwnPlayer() function. This will prevent others from mucking about with the library while you're using it, since most library functions will be locked out to everyone but you. Of course, anyone can *see* what you're doing with the library by simply examining the library base structure, and this is exactly what the LScope program does. Also, certain functions like CalcElapsedTime(), as well as the status signal functions are always available to everyone regardless of who might own the library. Anyway, here is an explanation of each field in the library base structure (excluding the standard library structure fields, that is). APTR dtl_SysLib This field contains a pointer to Exec Base that you can use. APTR dtl_DosLib This field contains a pointer to the dos library base structure for you to use. If you open destracker.library, then you won't need to open dos.library, as this is already done for you. :) APTR dtl_RexxSysLib This is a pointer to the Rexx Syslib base structure. You shouldn't need to use this. It's mostly just for me. APTR dtl_SegList This is a sacred field for internal library use only. Oooo. Don't muck about with it. APTR dtl_System Another sacred field. UBYTE dtl_SysFlags Yet another sacred field. UBYTE dtl_WhichTimer (New field for release 2.00, lib v3.0) This field tells you which CIA timer is being used by DES-Tracker. It holds one of the following values: Value Timer being used: 0 CIA A, Timer A 1 CIA A, Timer B 2 CIA B, Timer A 3 CIA B, Timer B Another way of looking at it is this: Bit 1 of the dtl_WhichTimer field tells you which CIA is being used (0=CIA A, 1=CIA B) and bit 0 tells you which timer on that CIA is being used (0=Timer A, 1=Timer B). APTR dtl_ModPathList This field contains a pointer to the first entry in a linked list of PATHENTRY structures. A PATHENTRY structure defines a single search path for use by the LoadModule() routine. If the list is empty, then this field contains NULL. See the description of the PATHENTRY structure above for more information regarding this. See also the LoadModule() function description in the LibFuncs.DOC file. UWORD dtl_Flags This is a very useful field. This field contains 16 flags that you can use for various means. They are as follows (accompanied by their bit position within the word. They are listed in bit order from left to right). Bit 15 DF_LIBLOCKED This bit is set to 1 whenever someone has owned the library (see the OwnPlayer function in LibFuncs.DOC). If it is 0, then everyone has access to all library functions. Bit 14 DF_MODULECHANGED This bit toggles between 0 and 1 whenever a physical change is made to a currently loaded module (i.e. if it is retitled or has its tempo altered real permanent-like). To accurately monitor changes to a module, you should monitor this bit from an interrupt (a vblank may do, but a timer interrupt works better, although timer interrupt sources are at a premium). This bit is only valid if a module is loaded into memory. Bit 13 DF_LOOPINTENT Although the description of this bit (the next paragraph) still stands, it should be noted that this field is pretty much useless now. This is because of the addition of the Iterations field in the PSC0 construct appended to the end of all song modules saved from DES-Tracker (except DES-Tracker v1.0 format ("DTL0") which doesn't need a PSC) construct appended to it). This bit is essentially ignored by the library itself, although the library has a function that allows you to set/clear it. It purpose is for users that need to know whether a song is meant to loop (as opposed to playing once and finishing). When you load save a song back to disk (using SaveModule), the status of this bit is saved along with the song. That way, when you load the song some other time, you can check this bit to see if the song is supposed to loop or not and act accordingly (e.g. you could play the song for 2 iterations instead of 1 and fade the song out on the second iteration. The Jukebox.rexx program included with this package does exactly this). Bit 12 DF_AUTOTIMING This is the auto-timing detection flag (see SetAutoTiming function in LibFuncs.DOC). If this bit is set, then auto timing is enabled and the library will automatically switch to the timing mode (50 or 60Hz) whenever a song is loaded that contains a PSC0 construct (see DTLib.DOC about the PSC0 construct). If the bit is 0, then auto timing is disabled and must be set manually (using the SetAutoTiming function). Bit 11 DF_CH3NOTEHIT This bit toggles between 0 and 1 whenever a new note is played in audio channel #3. This bit is unaffected by effects such as pitch bends, etc. It only reflects new note hits (not modifications to a playing note). Of course, this bit is only valid if a module is actually playing. Bit 10 DF_CH2NOTEHIT Same as bit 11 above, but reflects new note hits in audio channel #2 instead. Bit 9 DF_CH1NOTEHIT Same as bit 11 above, but applies to audio channel #1. Bit 8 DF_CH0NOTEHIT Same as bit 11 above, but applies to audio channel #0. Bit 7 DF_PLAYING If this bit is set to 1, then it means a module is currently playing. This, of course also means that a module is loaded. If this bit is 0, then no module is playing (but this does not necessarily tell you whether a module is loaded or not). Bit 6 DF_PLAYSEQDONE When a play sequence is started, this bit is automatically cleared. It will be automatically set to 1 when the play sequence is finished. This bit is unaffected by pausing the play sequence. It's set to 1 only when the end of the play sequence has been reached. Bit 5 DF_MODULELOADED This bit is set to 1 whenever a module is currently loaded, and it is cleared whenever a module is unloaded from memory. Bit 4 DF_FILTERSTATUS This bit tells you if the Amiga lo-pass filter is enabled or not. If this bit is set to 1, then the filter is currently on. If it's 0, then its off. Bit 3 DF_CH3STATUS This bit holds the channel enabled status for audio channel #3. If this bit is set to 1, then audio channel #3 is enabled. If it is 0, then audio channel #3 is disabled and can be used by other applications without library player interference. Bit 2 DF_CH2STATUS Same as bit 3 above, but applies to audio channel #2 instead. Bit 1 DF_CH1STATUS Same as bit 3 above, but applies to audio channel #1. Bit 0 DF_CH0STATUS Same as bit 3 above, but applies to audio channel #0. Note that the above bit field names are defined in DTLib.I as bit numbers. The bit mask values for these bit fields use the same name with a prefix of "DFM_" instead of "DF_". UWORD dtl_Flags2 This field is new for release 1.2 of DES-Tracker. As of release 1.62, another flag has been added to this field. See the History.TXT file. Bit 15 DF_TEMPOINT This flag contains the current tempo interpretation setting. If this bit is clear (default), then "BPM" ("Beats" Per Minute) tempos are enabled. If this bit is set, then BPM tempos are disabled, and all tempo values are treated normally. See the "SetTempoInt" function in the "LibFuncs.DOC" file for more information about this setting. Bit 14 DF_HASPSC0 This flag is new for version 2.3 of destracker.library. Modules saved from DES-Tracker automatically get a special data construct appended at the end of them. This data construct is called a "PSC0 construct". "PSC" means "Play Status Construct", and it contains the kind of information that should have been made a part of the tracker module file format in the first place. Things like the default timing (50/60 hertz), # of iterations, etc. This flag is either set or cleared by the LoadModule() function when it loads a new module from disk. If this flag is set when LoadModule() returns, then the module had a PSC0 construct appended to it. If it's 0, then no construct was found. A PSC0 construct can be removed from a file by loading it into an appropriate tracker editor and saving it back. UBYTE dtl_GlobalVolume This field contains the current global volume setting, and is a value in the range 0..64 inclusive, with 0 being silent and 64 being maximum volume. BYTE dtl_GlobalTempo The current global tempo can be obtained from this field. It contains a relative offset to the normal tempo of the song (i.e. 0 means normal tempo, -1 means play slightly faster and +1 means play slightly slower). The tempo is actually a delay value, which is why higher values make the song play slower, not faster. BYTE dtl_FineTempo (Contents redefined for release 2.00, lib v3.0) The fine tempo is a value in the range -128..127 inclusive, and is a fine global tempo adjustment. You can use the fine tempo to adjust the playback tempo of a song by plus or minus 10Hz from the base timing frequency. The fine tempo value is specified in units of 0.078125Hz. So, if you specify a fine tempo of 53 (for example), you will increase the overall tempo of the song by (53 * 0.078125) = +4.14Hz. In the extremes, a fine tempo of -128 will slow down the tempo by -10Hz and a fine tempo of +127 will speed up the tempo by +10Hz. Setting the fine tempo is most useful when you have a song that uses long samples (of, for example, complete drum beats or people singing) that are not synchronized properly to the rest of the music at the base timing mode frequency. By using fine tempo you can tweak the song's overall tempo to make these long samples synchronize properly. When you save a song module from DES-Tracker, it will include the fine tempo setting in the file, and will automatically set it when you load the song from then on. UBYTE dtl_DefaultTempo Amazingly enough, some people compose tunes and use no tempo comands in them, assuming that everybody will always play the song using only the editor that they wrote it on (which has a default tempo). Songs of this type cannot have their tempo permanently altered (using the ApplyGlobalTempo function. See LibFuncs.DOC). Since the library therefore supports it's own adjustable default tempo, this field contains its current setting. This field is set to 6 by default when the library is first opened. UBYTE dtl_VolFadeRate This field contains the current rate at which volume fades occur (see FadeGlobalVolume and SetVolFadeRate functions in LibFuncs.DOC). The higher the number, the slower the fade. UBYTE dtl_Iterations The current number of times that a play sequence will be played (from start to end) is stored here. A value of 0 means that the play sequence, once started, will iterate forever. UBYTE dtl_TimingMode This field contains either 0 if the current timing mode is NTSC, or 1 if the current timing mode is PAL. DES-Tracker will default to NTSC if run on an NTSC Amiga, and PAL if run on a PAL Amiga. Unlike some other CIA-timer players, DES-Tracker compensates for the difference between PAL and NTSC CIA base frequencies. Betcha didn't know that. ;) UBYTE dtl_SaveFormat (Contents changed as of release 2.00, lib v3.0) This field contains the currently selected module save format. Currently, it will be one of the following values: 0 = SoundTracker v2.6 format 1 = NoiseTracker/ProTracker format 2 = DES-Tracker v1.0 format ("DTL0") You set the module save format by using the SetSaveFormat() function. The default value is 0. UBYTE dtl_PlayStatus (New field as of release 1.6) This field is new for DES-Tracker release 1.6. It contains the current play state of the library and is an added convenience to the already existing flags fields in this structure (see dtl_Flags and dtl_Flags2 above). This field will always contain one of the following values (defined in DTLib.I and DTLib.H): PS_NOMODULE = 0 No module is loaded. PS_IDLE = 1 Module loaded but hasn't started playing yet. PS_PLAYING = 2 Module is currently playing. PS_PAUSED = 3 Module is paused. PS_STOPPED = 4 Module was playing but has been stopped. PS_PLAYSEQDONE = 5 Module has finished playing. UBYTE dtl_DefIterations (New field as of release 2.00, lib v3.0) This field holds the default number of iterations for the currently loaded song module. If the song file contained a PSC0 construct at the end of it, then this field will hold the number of iterations specified in the PSC0 construct. Once a song module is loaded, this field will NOT change if you change the number of iterations for the play sequence. This purpose of this field is to allow the user to know what the original number of iterations are for the song, even if the current number of iterations has been changed since the song was loaded. As an example of this field's use, the MODInfo program tells the user how long a given song will take to play if it is played by the mJuke program. To do this it needs to know how many iterations the song is meant to play for. mJuke changes the number of iterations for a song (it usually adds an extra iteration which it uses for the final volume fade). If MODInfo is run for a song that is currently playing, then MODInfo can't look at the "dtl_Iterations" field, because if mJuke is playing the song, then it has changed the number of iterations. So, MODInfo looks instead to this field so it can then determine how many iterations mJuke will play. Note however, that if you save the song using the SaveModule() function, the contents of "dtl_Iterations" will be copied here. This will reflect the new default number of iterations for the song file. UBYTE dtl_IterationsToGo This field is only valid while a song is playing. It holds the number of iterations remaining in the play sequence (including the iteration currently playing). If the number of iterations (dtl_Iterations, above) is set to 0, then this field will also contain 0 (which means the play sequence will loop forever). UBYTE dtl_CurPosition Also valid only while a song is playing, this field contains the current position in the play sequence. A value of 0 represents the first position in the song. UBYTE dtl_CurNoteIndex This field contains the current note index (0..63 inclusive) within the current position. This field only valid while a song is playing. UBYTE dtl_StartPosition This field contains the currently defined start position for the play sequence. A value of 0 refers to the first position in the song. This field is valid only while a module is loaded. UBYTE dtl_StartNoteIndex Contains the start note index within the start position at which the play sequence will begin. Range is 0..63 inclusive. Valid only while a module is loaded. UBYTE dtl_EndPosition This contains the currently defined end position for the play sequence. This field is valid only while a module is loaded. UBYTE dtl_EndNoteIndex Contains the end note index within the end position for the play sequence. Note that any notes/commands at this position will NOT get processed. This field is valid only while a module is loaded. UBYTE dtl_CurrentTempo Contains the current tempo of the song, including any adjustment caused by the global tempo setting. This is a value from 0..255 inclusive. 0 is very fast, and 255 is treacherously slow. A value of 6 is the default tempo for most tracker editors. This value may change throughout the course of a song. This field is only valid while a song is playing. STRUCT dtl_Channel0,cs_SIZE This is the CHANNELSTATUS structure for audio channel #0. Note that this is an instance of the structure and not a pointer to one. The contents of this structure are only valid while a song is playing. STRUCT dtl_Channel1,cs_SIZE This is the CHANNELSTATUS structure for audio channel #1. See the description of the CHANNELSTATUS structure earlier in this document for more information regarding this. STRUCT dtl_Channel2,cs_SIZE The CHANNELSTATUS structure for audio channel #2. STRUCT dtl_Channel3,cs_SIZE The CHANNELSTATUS structure for audio channel #3. STRUCT dtl_ModuleStatus,ms_SIZE This is an instance of a MODULESTATUS structure used for a module when it is loaded. It's contents are only valid when a module is loaded. See the description of the MODULESTATUS structure earlier in this document for more information. UBYTE dtl_ElapsedHours This field contains the number of hours that have elapsed since a play sequence was started. The elapsed time is reset to 00:00:00:00 whenever a play sequence is started. The elapsed time is suspended whenever a play sequence is paused, and continued when the play sequence proceeds from its paused state. This field contains a value from 0..255 inclusive. UBYTE dtl_ElapsedMinutes This field contains the elapsed minutes of a play sequence. It ranges from 0..59 inclusive. UBYTE dtl_ElapsedSeconds Contains the elapsed seconds portion of a play sequence. It's contents range from 0..59 inclusive. UBYTE dtl_ElapsedJiffies Contains the elapsed jiffies (i.e. 60ths of a second) portion of a play sequence. It's contents range from 0..59 inclusive. ULONG dtl_ElapsedTime (New field for release 2.00, lib v3.0) Contains the total elapsed time of the currently playing song module in 60ths of a second. Useful if you need this value and you don't want to have to get it by doing multiplications with the previous four fields. ULONG dtl_CurrentHertz (New field for release 2.00, lib v3.0) This holds the current frequency of the player interrupt in hertz. This value is a fixed-point integer. That is, the upper word holds the integer portion of the frequency and the lower word holds the fractional portion of the frequency. If you want this value as a float (for C programmers), you would do the following: float freq; freq = ((float)(DTLBase -> dtl_CurrentHertz)) / 65536; LABEL dtl_SIZE This is an equate. It is defined as the size of the library base structure. It only appears in the "dtlib.i" (not in "dtlib.h") since it is only needed for assembly language programmers. ----------------------------------------------- End of Structures.DOC