destracker.library v1.1 Documentation Written by Darren Schebek Copyright (c)1992 by Darren Schebek Last updated: May 22, 1992 Library Structures Documentation -------------------------------- This file contains documentation regarding the custom structures used by the soundtracker.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). ----------------------------------------------- The MODULESTATUS Structure The MODULESTATUS structure contains informatin which is specified to any 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, so I'll just describe each field here in the order that they appear in the structure definition. 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 This longword field contains the length of the module in memory. It is (usually) the same as the file size on disk (ie, it includes the lengths of all instruments, song data, etc). Since Noisetracker and Protacker modules are converted to Soundtracker v2.6 format once loaded into memory, their size usually diminishes by anywhere from 1-30%, depending on the module being loaded. The new size is the size that will be stored in this field. Were you to save the module back to disk using the SaveModule function (see LibFuncs.DOC and RexxFuncs.DOC), the size stored here will be the size of the saved module. APTR ms_Address This is a pointer field. It contains a pointer to the song data in memory. It is very important to note that this is not a pointer to the entire song module in one big hunk of memory. It points to the entire module less the instrument data, so you cannot access the instrument sample data directly from this pointer. Also keep in mind that the module is in Soundtracker v2.6 format in memory, regardless of the format of the module when it was loaded. 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 Soundtracker v2.6 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). Both of these labels are defined in DTLibs.I. 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 ways 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 (Remember that the module in memory is always in Soundtracker v2.6 format, which records each pattern individually). 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). 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 is 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 # of the slot used by this instrument. There are 31 possible slots available for use in a module file. Slots are number 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 (eg, a single sample of a complete drum beat that must be timed perfectly with the rest of the music. Since percussion instruments have no deiscernable pitch per se, altering their pitch with the fine tune value does not typically affect the sound of the drums). 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 in 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 mostly 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 mostly 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). 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. LABEL cs_SIZE This is a equate. It is defined as the size of the CHANNELSTATUS structure. ----------------------------------------------- The LIBRARY BASE Structure This soundtracker.library'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). This will prevent others from mucking about with the library while you're using it, since all 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. 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 soundtracker.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 base use only. Oooo. Don't muck about with it. APTR dtl_System Another sacred field. UBYTE dtl_SysFlags Yet another sacred field. UBYTE dtl_Reserved1 A reserved field. This should always contain 0. APTR dtl_DefaultPath This field contains either a pointer to a NULL-terminated string or is itself NULL. If the former is the case, then the string in question is the default path that is used for all file operations wherein no path is specified. If this field contains NULL, then a file operation with no specified path will default to the current directory setting of the parent process from which the function is called (ie, the CLI). 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 (ie, 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 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 (eg, 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 13 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 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_". 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 (ie, 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 The fine tempo is a value in the range -128..127 inclusive, and is a fine global tempo adjustment. the resolution of the fine tempo is in approximately 1/12000 seconds (I think :). This tempo affects the BASE frequency of the CIA interrupt under which the library's player logic runs. Any alteration to the fine tempo of course is multiplied by the current tempo, but you don't need to worry about all this. For NTSC the fine tempo can adjust the base timing from 60Hz up to 120Hz and down to 40Hz. For PAL, timing is affected anywhere from 50Hz up to 85Hz and down to 35Hz. Fine tempo is used to tune a song's tempo to a comfortable speed, or to adjust the tempo finely for special looping instruments. When you save a song to disk using the library's SaveModule function, this fine tempo value is saved along with the song and is automatically set every time you load the song after that. 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 permenently 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. 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. 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 play 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 tany 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. It's 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 sudio channel #1. 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. 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 (ie, 60ths of a second) portion of a play sequence. It's contents range from 0..59 inclusive. LABEL dtl_SIZE This is an equate. It is defined as the size of the library base structure. ----------------------------------------------- End of Structures.DOC