2 @MASTER "Work:SC/XM/Autodocs/xmodule.doc"
3 @REMARK This file was created by ADtoHT 2.1 on 08-Apr-97 12:17:15
5 @REMARK ADtoHT is © 1993-1995 Christian Stieber
7 @NODE MAIN "xmodule.doc"
11 @{"background" LINK "background"}
13 @{"xmActivateSong()" LINK "xmActivateSong"} @{"xmAddHook()" LINK "xmAddHook"} @{"xmAddHookA()" LINK "xmAddHook"}
14 @{"xmAddInstrument()" LINK "xmAddInstrumentA"} @{"xmAddInstrumentA()" LINK "xmAddInstrumentA"} @{"xmAddPattern()" LINK "xmAddPatternA"}
15 @{"xmAddPatternA()" LINK "xmAddPatternA"} @{"xmAddSong()" LINK "xmAddSongA"} @{"xmAddSongA()" LINK "xmAddSongA"}
16 @{"xmCreateSong()" LINK "xmCreateSong"} @{"xmCreateSongA()" LINK "xmCreateSong"} @{"xmDeleteSong()" LINK "xmDeleteSong"}
17 @{"xmDisplayMessage()" LINK "xmDisplayMessage"} @{"xmDisplayMessageA()" LINK "xmDisplayMessage"} @{"xmDisplayProgress()" LINK "xmDisplayProgress"}
18 @{"xmIdentifyModule()" LINK "xmIdentifyModule"} @{"xmLoadModule()" LINK "xmLoadModuleA"} @{"xmLoadModuleA()" LINK "xmLoadModuleA"}
19 @{"xmLockActiveSong()" LINK "xmLockActiveSong"} @{"xmProcessSong()" LINK "xmProcessSongA"} @{"xmProcessSongA()" LINK "xmProcessSongA"}
20 @{"xmRemHook()" LINK "xmRemHook"} @{"xmRemHookA()" LINK "xmRemHook"} @{"xmRemInstrument()" LINK "xmRemInstrument"}
21 @{"xmRemPattern()" LINK "xmRemPattern"} @{"xmRemSong()" LINK "xmRemSong"} @{"xmSaveModule()" LINK "xmSaveModuleA"}
22 @{"xmSaveModuleA()" LINK "xmSaveModuleA"} @{"xmSetInstrument()" LINK "xmSetInstrumentA"} @{"xmSetInstrumentA()" LINK "xmSetInstrumentA"}
23 @{"xmSetPattern()" LINK "xmSetPatternA"} @{"xmSetPatternA()" LINK "xmSetPatternA"} @{"xmSetSongLen()" LINK "xmSetSongLen"}
26 @NODE "background" "xmodule/background (information)"
30 The xmodule.library is an API that provides access to the XModule
31 song management engine, as well as other general pourpose
32 services. Hooks and external applications can use this library
33 to create, load, save and modify songs.
35 The xmodule.library does not exist as a stand alone shared libray.
36 Instead, it's code is contained inside the main XModule executable
37 (altrough it's logically independant from the rest of the XModule
40 XModule adds the xmodule.library to the exec libray list at
41 startup time, unless it finds one already in the list (this might
42 happen when multiple copies of XModule are running at the same
46 The xmodule.library maintains a list of public songs which can be
47 used by all applications which opened the library. Each song in
48 the list is protected from multiple task access by a
49 SignalSemaphore, and whole list is also protected by another
50 semaphore. The locking mechanism is very simple: before you can
51 access a song you must obtain its semaphore, and you must release
52 it as soon as you are done with it. If you are locking a song to
53 just to read some information (i.e.: you don't want to modify
54 anything), you should obtain a shared lock instead of an exclusive
55 one. The list must be locked whenever you want to add or remove
56 a song, or when you scan it in any way.
58 Since public songs could be modified or even deleted by other
59 tasks, do not make your songs public unless your code is smart
60 enough to handle all possible situations.
64 Actually, most modular programs call them `modules', but it would
65 have created a lot of confusion with a program like XModule :-).
67 Hooks are programs that add some kind of functionality
68 to XModule. External hook files are standard shared libraries
69 which will open the xmodule.library when they are loaded and
70 call @{"xmAddHookA()" LINK "xmodule/xmAddHook"} to add themselves to a list of hooks maintained
73 Currently, XModule supports two kinds of hooks: loaders and
74 savers. Loader hooks can also provide a function which
75 identifies a particular module format.
77 An external hook libray may also contain several hooks.
78 Putting a loader and a saver for one particolar format together
79 in one libray is generally a good idea, while making a hook
80 with hundereds of loaders and savers isn't a good move because
81 it makes the whole concept of external hooks quite useless.
82 Grouping different versions or variants of one format together
83 in one external hook is acceptable.
86 songclass/--background--, exec/ObtainSemaphore()
89 @NODE "xmActivateSong" "xmodule/xmActivateSong()"
93 xmActivateSong -- Makes a song the active one@{b}
96 success = xmActivateSong(songInfo);
99 ULONG xmActivateSong(@{"struct SongInfo" LINK "songclass.h/File" 284} *);@{b}
102 Makes the passed song the currently active one. It's pointer
103 will be stored in the public song list and most actions
104 will happen on this song by default.@{b}
107 songInfo - song to be activated. If NULL, this function will
111 success - Will be 0 for failure, in which case the song will
112 not be removed from the song list. Currently,
113 xmActivateSong() will never fail.@{b}
116 In order to activate a song, you must own a shared lock
117 on it. Please do not hog this lock for a long time when
118 xmActivateSong() returns, because most internal routines
119 try to lock the current song before taking any action.@{b}
124 @NODE "xmAddHook" "xmodule/xmAddHook()"
128 xmAddHookA -- Creates a new XModule Hook
129 xmAddHook -- Varargs stub for xmAddHookA@{b}
132 hook = xmAddHookA(tagList)
135 @{"struct XMHook" LINK "xmodule.h/File" 92} *xmAddHookA(struct TagItem *);
138 hook = xmAddHook(Tag1,...)
140 @{"struct XMHook" LINK "xmodule.h/File" 92} *xmAddHook(ULONG,...);@{b}
143 Creates a new XMHook structure and fills it in with data supplied
144 with the TagList. Adds the newly created Hook to the appropriate
148 tagList - pointer to a tag list specifying how to initialize the
149 XMHook structure.@{b}
152 @{"XMHOOK_Type" LINK "xmodule.h/File" 235} - (ULONG) Defines the pourpose of this hook. Possible
153 values are currently @{"NT_XMLOADER" LINK "xmodule.h/File" 138} and @{"NT_XMSAVER" LINK "xmodule.h/File" 139}. (This
156 @{"XMHOOK_Name" LINK "xmodule.h/File" 236} - (STRPTR) ti_Data contains a short name for the
157 hook (e.g: "SoundTracker"). This name will appear in the
158 Savers list if this hook is a saver and will be passed as an
159 argument for some ARexx commands, so please use a single
160 word name. (This tag is REQUIRED).
162 @{"XMHOOK_Priority" LINK "xmodule.h/File" 237} - (BYTE) Priority to give to this hook. Hooks
163 with higher priorities will be used before lower priority
164 ones and will come first in lists shown to the user. Valid
165 range is -128..+127, but please restrict to a -20..+20
166 interval for normal cases. (Defaults to 0).
168 @{"XMHOOK_Descr" LINK "xmodule.h/File" 238} - (STRPTR) Verbose description of the hook
169 (without newlines). (Defaults to NULL).
171 @{"XMHOOK_Author" LINK "xmodule.h/File" 239} - (STRPTR) Author's name. Please, just put
172 your full name here; no greetings, copyright notices,
173 etc. (Defaults to NULL).
175 @{"XMHOOK_ID" LINK "xmodule.h/File" 240} - (ULONG) This is a unique, IFF-style identifier for
176 the format. If the format is an IFF format, it must be the
177 same of the FORM ID. (Defaults to 0, this tag is required
178 for IFF loaders and savers).
180 @{"XMHOOK_Flags" LINK "xmodule.h/File" 241} - (ULONG) Sets miscellaneous flags for this hook.
181 See xmodule.h for possible flags.
183 @{"XMHOOK_LibraryBase" LINK "xmodule.h/File" 243} - (struct Library *) Pointer to the library
184 base for external hooks. This pointer will be used to open
185 the library when the hook is created and to close it when
186 the hook is deleted. If you do not pass this tag, you must
187 find some other way to keep your code in memory until one
188 or more of your hooks are active. XModule will close your
189 library just after calling the SetupXMHook() function.
192 @{"XMHOOK_UserData" LINK "xmodule.h/File" 242} - (APTR) ti_Data will be stored in the
193 xmh_UserData field of the XMHook structure. This field can
194 come andy to store private data. (Defaults to NULL).
196 XMHOOK_RemoveHookFunc - (APTR) Pointer to a function which will be
197 called upon removing the hook. This function can be used to
198 free any private resources allocated by the hook when it was
199 created. The template for the function is:
201 void RemoveHookFunc (@{"struct XMHook" LINK "xmodule.h/File" 92} *hook);
204 @{"XMHOOK_LoadModFunc" LINK "xmodule.h/File" 245} - (APTR) Pointer to the hook function which
205 loads a module. The template for the function is:
207 LONG LoadModFunc (BPTR fileHandle, @{"struct SongInfo" LINK "songclass.h/File" 284} *song,
209 @{"struct XMHook" LINK "xmodule.h/File" 92} *loader);
212 `fileHandle' is an open file to load the module from. The
213 caller will take care to close it for you. The loader should
214 return RETURN_OK for success, or any other AmigaDOS error
215 code to mean failure. In particular, RETURN_WARN indicates
216 that something went wrong, but the song is ok. The special
217 error code @{"ERROR_IOERR" LINK "xmodule.h/File" 194} can be used when some dos.library
218 call (e.g.: Read()) failed. In the latter case, the
219 AmigaDOS IoErr value should be set to explain the specific
220 cause of the problem.
221 (This tag is required by all @{"NT_XMLOADER" LINK "xmodule.h/File" 138} type hooks).
223 @{"XMHOOK_SaveModFunc" LINK "xmodule.h/File" 246} - (APTR) Pointer to the hook function which
224 saves a module. The template for the function is:
226 LONG SaveModFunc (BPTR fileHandle, @{"struct SongInfo" LINK "songclass.h/File" 284} *song,
228 @{"struct XMHook" LINK "xmodule.h/File" 92} *saver);
231 fileHandle is an open file to save the module to. The caller
232 will take care to close it for you. The saver should return
233 RETURN_OK for success, or any other AmigaDOS error code to
234 mean failure. In particular, RETURN_WARN indicates that
235 something went wrong, but the song is ok. The special
236 error code @{"ERROR_IOERR" LINK "xmodule.h/File" 194} can be used when some dos.library
237 call (e.g.: Read()) failed. In the latter case, the
238 AmigaDOS IoErr value should be set to explain the specific
239 cause of the problem.
240 (This tag is required by all @{"NT_XMSAVER" LINK "xmodule.h/File" 139} type hooks).
243 @{"XMHOOK_IdentifyModFunc" LINK "xmodule.h/File" 247} - (APTR) Pointer to the hook function
244 which identifies a module format. The template for the
247 @{"struct XMHook" LINK "xmodule.h/File" 92} *IdentifyModFunc (BPTR fileHandle,
249 @{"struct XMHook" LINK "xmodule.h/File" 92} *hook,struct TagItem *tagList);
252 fileHandle is an open file to try the identification on. The
253 caller will take care to close it. NOTE: Do not make assumptions
254 on the initial file position (e.g: seek yourself to position 0
255 if you need to). This funtion should return a pointer to a valid
256 loader (usually the one passed in) if the format is recognized,
257 NULL otherwhise. (This tag is required by all @{"NT_XMLOADER" LINK "xmodule.h/File" 138} type
261 hook - Pointer to the newly allocated XMHook structure, or
262 NULL for failure.@{b}
265 @{"xmRemHook()" LINK "xmRemHook"}, @{"xmIdentifyModule()" LINK "xmIdentifyModule"}, xmLoadSong(), xmSaveSong()
268 @NODE "xmAddInstrumentA" "xmodule/xmAddInstrumentA()"
272 xmAddInstrumentA -- Adds a instrument to a song
273 xmAddInstrument -- Varargs stub for xmAddInstrumentA@{b}
276 instrument = xmAddInstrumentA(si, instrNum, tagList)
279 @{"struct Instrument" LINK "songclass.h/File" 183} *xmAddInstrumentA(@{"struct SongInfo" LINK "songclass.h/File" 284} *,LONG,
283 instrument = xmAddInstrument(si,instrNum,tag1,...)
285 @{"struct Instrument" LINK "songclass.h/File" 183} *xmAddInstrument(@{"struct SongInfo" LINK "songclass.h/File" 284} *,LONG,LONG,...);@{b}
288 Adds an instrument to a song by calling the @{"SNGM_ADDINSTRUMENT" LINK "songclass.h/File" 32} method .@{b}
291 si - pointer to the song to which the instrument should be added.
292 tagList - optional TagList. See @{"SNGM_ADDINSTRUMENT" LINK "songclass.h/File" 32} for possible tags .@{b}
295 Pointer to the new instrument or NULL for failure.@{b}
298 In order to add instruments, you should have exclusive access to
299 the song. Always obtain a lock before you call this function on
303 @{"xmRemInstrument()" LINK "xmRemInstrument"}, @{"songclass" LINK "songclass/MAIN"}/SNGM_REMINSTRUMENT
306 @NODE "xmAddPatternA" "xmodule/xmAddPatternA()"
310 xmAddPatternA -- Adds a pattern to a song
311 xmAddPattern -- Varargs stub for xmAddPatternA@{b}
314 pattern = xmAddPatternA(si, tagList)
317 @{"struct Pattern" LINK "songclass.h/File" 229} *xmAddPatternA(@{"struct SongInfo" LINK "songclass.h/File" 284} *,struct TagItem *);
320 pattern = xmAddPattern (si,tag1,...)
322 @{"struct Pattern" LINK "songclass.h/File" 229} *xmAddPattern(@{"struct SongInfo" LINK "songclass.h/File" 284} *,LONG Tag1,...);@{b}
325 Adds a pattern to a song by calling the @{"SNGM_ADDPATTERN" LINK "songclass.h/File" 29} method.@{b}
328 si - pointer to the song to which the pattern should be added.
329 tagList - optional TagList. See @{"SNGM_ADDPATTERN" LINK "songclass.h/File" 29} for possible tags.@{b}
332 Pointer to the new pattern or NULL for failure.@{b}
335 In order to add patterns, you should have exclusive access to
336 the song. Always obtain a lock before you call this function on
340 @{"xmRemPattern()" LINK "xmRemPattern"}, @{"songclass" LINK "songclass/MAIN"}/SNGM_ADDPATTERN
343 @NODE "xmAddSongA" "xmodule/xmAddSongA()"
347 xmAddSongA -- Add a song to the song list
348 xmAddSong -- Varargs stub for xmAddSongA@{b}
351 success = xmAddSongA(songInfo,position,tagList);
354 ULONG xmAddSongA(@{"struct SongInfo" LINK "songclass.h/File" 284} *,@{"struct SongInfo" LINK "songclass.h/File" 284} *,
358 success = xmAddSong(songInfo,position,tag1,...);
360 ULONG xmAddSong(@{"struct SongInfo" LINK "songclass.h/File" 284} *,@{"struct SongInfo" LINK "songclass.h/File" 284} *,
364 Adds a song to the public song list. Trying to add a song
365 twice is harmless.@{b}
368 songInfo - song to be added. Passing a NULL pointer is safe.
369 position - Position to add the song in. Passing NULL adds the
370 song in the head of the list, while ~0 adds it in the tail.
371 passing a pointer to a SongInfo already in the list inserts
372 the first song _after_ the other one.
373 tagList - pointer to a TagList for more arguments.@{b}
376 @{"XMSNG_Active" LINK "xmodule.h/File" 209} - (BOOL) Makes this song the active one. The
377 default is to just add the song without activating it.@{b}
380 success - Will be 0 for failure, in which case the song will
381 not be added to the songs list. Currently, xmAddSongA()
385 The song list is protected from multiple tasks access by a
386 SignalSemaphore in XModuleBase. This call will wait if the
387 song list has been locked by another task. Beware of deadlock
391 @{"xmRemSong()" LINK "xmRemSong"}
394 @NODE "xmCreateSong" "xmodule/xmCreateSong()"
398 xmCreateSongA -- Create and initialize a new SongInfo structure
399 xmCreateSong -- Varargs stub for xmCreateSongA@{b}
402 songInfo = xmCreateSongA(tagList);
405 @{"struct SongInfo" LINK "songclass.h/File" 284} *xmCreateSongA(struct TagItem *);
408 songInfo = xmCreateSong(Tag1,...);
410 @{"struct SongInfo" LINK "songclass.h/File" 284} *xmCreateSong(ULONG,...);@{b}
413 Allocates and initializes a new SongInfo structure. The song
414 can then be added to the song list via @{"xmAddSongA()" LINK "xmAddSongA"}, in which
415 case, it is no longer required to free it with @{"xmDeleteSong()" LINK "xmDeleteSong"}.@{b}
418 tagList - pointer to an optional tag list specifying how to
419 initialize the SongInfo structure.@{b}
422 @{"SNGA_DefaultTracks" LINK "songclass.h/File" 121} - Sets the default number of pattern tracks for
423 the song. Defaults to 4.
425 @{"SNGA_DefaultPattLen" LINK "songclass.h/File" 122} - Sets the default number of pattern lines for
426 the song. Defaults to 64.
428 @{"SNGA_ReadyToUse" LINK "songclass.h/File" 127} - Adds one pattern and one position to the song.
431 @{"XMSNG_AddToList" LINK "xmodule.h/File" 205} - (@{"struct SongInfo" LINK "songclass.h/File" 284} *) Add the song to the song list.
432 When a song is being added to the list, a shared lock is
433 obtained on it to prevent other tasks from modifying (or even
434 remove) the song before you can do your job on it. IT IS YOUR
435 DUTY TO UNLOCK THE SONG as soon as you are done modifying it.
436 Passing NULL adds the song on the head of the list, while -1
437 (~0) will add it to the end of the SongList. Passing in a
438 pointer to another song which is already in the list, will
439 add the new song _after_ the latter.
440 (Default is not adding the song).
442 @{"XMSNG_Active" LINK "xmodule.h/File" 209} - (BOOL) Makes this song the active one. This tag is
443 considered only if the @{"XMSNG_AddToList" LINK "xmodule.h/File" 205} tag is also passed.@{b}
446 songInfo - pointer to the newly allocated SongInfo structure, or
447 NULL for failure.@{b}
450 @{"xmDeleteSong()" LINK "xmDeleteSong"}, @{"xmAddSongA()" LINK "xmAddSongA"}
453 @NODE "xmDeleteSong" "xmodule/xmDeleteSong()"
457 xmDeleteSong -- Deletes a song@{b}
460 xmDeleteSong(songInfo)
463 void xmDeleteSong(@{"struct SongInfo" LINK "songclass.h/File" 284} *);@{b}
466 Deletes a song and all the items attached to it (patterns,
467 instruments, etc.). This call will also remove the song from
468 the song list if it had been added to it.@{b}
471 songInfo - pointer to the SongInfo structure to be deleted.
472 Passing a NULL pointer is harmless.@{b}
475 In order to delete a song which has been added to the public
476 song list, you must first obtain an exclusive lock on it to
477 prevent other tasks from walking on it while you are freeing
478 it's data structures. The semaphore does NOT need to be
479 relinquished, because the SongInfo structure won't exist any
480 more when this call returns.@{b}
483 @{"xmCreateSong()" LINK "xmCreateSong"}, @{"xmRemSong()" LINK "xmRemSong"}
486 @NODE "xmDisplayMessage" "xmodule/xmDisplayMessage()"
490 xmDisplayMessageA -- Displays a message to the user
491 xmDisplayMessage -- Varargs stub for xmDisplayMessageA()@{b}
494 xmDisplayMessageA(level, message, args)
497 void xmDisplayMessageA(ULONG,APTR,LONG *);
500 xmDisplayMessage(level, message, ...)
502 void xmDisplayMessage(ULONG,APTR,...);@{b}
505 Outputs a string in the XModule log window or in the 'action' field
506 of the progress indicator. The string is printf-formatted before
510 level - a number from 0 to 7 which indicates the importance of the
511 message. 7 is used for very annoying messages (eg: debug output) ,
512 0 for very important things (eg: disaster).
513 If you set the @{"XMDMF_USECATALOG" LINK "xmodule.h/File" 187} bit in the level parameter, you
514 can pass a catalog string number instead of a pointer to a string .
515 Specifying @{"XMDMF_ACTION" LINK "xmodule.h/File" 185}, the message will be put in the 'action'
516 field of the progress indicator.
517 If the flag @{"XMDMF_DOSFAULT" LINK "xmodule.h/File" 184} is specified, a Fault() output is
518 formatted using the message as an header. In this case, the
519 level parameter takes another meaing: The lower word can contain
520 an AmigaDOS error code. If it is 0, IoErr() will be used to get
522 message - pointer to a string or catalog message number,
523 when the @{"XMDMF_USECATALOG" LINK "xmodule.h/File" 187} flag is set.
524 args - arguments for formatting.@{b}
527 xmDisplayMessage (@{"XMDMF_ALERT" LINK "xmodule.h/File" 173},
528 "The application `%s' fucked up Windoze95 because %s.",
529 "(unknown name)", "an error occurred");
531 xmDisplayMessage (XMDMF_USE_CATALOG | @{"XMDMF_COMMENT" LINK "xmodule.h/File" 179},
532 MSG_LIFE_UNIVERSE_AND_ALLTHAT, 42, "Fortytwo", "For tea too");
534 xmDisplayMessageA (@{"XMDMF_ACTION" LINK "xmodule.h/File" 185} | @{"XMDMF_USECATALOG" LINK "xmodule.h/File" 187},
535 MSG_READING_COMICS, NULL);
537 xmDisplayMessage (@{"XMDMF_DOSFAULT" LINK "xmodule.h/File" 184} | @{"XMDMF_USECATALOG" LINK "xmodule.h/File" 187},
538 MSG_CANT_LOAD_MODULE, ModuleName);@{b}
541 @{"xmDisplayProgress()" LINK "xmDisplayProgress"}
544 @NODE "xmDisplayProgress" "xmodule/xmDisplayProgress()"
548 xmDisplayProgress -- Uptdates the progress bar indicator@{b}
551 abort = xmDisplayProgress(done, total)
554 LONG @{"xmDisplayMessageA" LINK "xmDisplayMessage"}(ULONG,ULONG);@{b}
557 Updates the position of the fuel gauge in the progress window to
558 show the progress of an operation. Additionally, it checks for
562 done - a number which indicates how much of the work has
563 been already completed
564 total - Total number of operations to do.@{b}
567 0 for success, ERROR_BREAK if user abort was detected. You should
568 always check this return code to abort what you were doing.
571 @NODE "xmIdentifyModule" "xmodule/xmIdentifyModule()"
575 xmIdentifyModule -- Returns the type of a module@{b}
578 loader = xmIdentifyModule(fh, tagList)
581 @{"struct XMHook" LINK "xmodule.h/File" 92} *xmIdentifyModule(BPTR,struct TagItem *);@{b}
584 Finds out a loader which is able to read the given module.@{b}
587 fh - AmigaDOS FileHandle to examine.
588 tagList - Additional parameters. Leave it NULL for now.@{b}
591 loader - Pointer to the first loader which knows how to load this
592 module, or NULL otherwise.@{b}
595 Before you call this function, you must first obtain a lock on the
596 loaders list to protect yourself from other tasks which might remove
597 the returned loader before you can actually use it.@{b}
602 @NODE "xmLoadModuleA" "xmodule/xmLoadModuleA()"
606 xmLoadModuleA -- Loads a module and converts it in XModule format
607 xmLoadModule -- Varargs stub for xmLoadModuleA@{b}
610 songInfo = xmLoadModuleA(fileName,tagList)
613 @{"struct SongInfo" LINK "songclass.h/File" 284} *xmLoadModuleA(STRPTR,struct TagItem *);
616 songInfo = xmLoadModule(fileName,tag,...)
618 @{"struct SongInfo" LINK "songclass.h/File" 284} *xmLoadModule(STRPTR,LONG,...);@{b}
621 Loads fileName using the correct module loader.@{b}
624 fileName - File to read. Can be NULL if the @{"XMSNG_FileHandle" LINK "xmodule.h/File" 208}
626 tagList - Additional parameters (see below). Can be NULL.@{b}
629 @{"XMSNG_OldSong" LINK "xmodule.h/File" 206} - ti_Data is the pointer to a SongInfo which will be
630 freed as soon as the module format has been determined. This
631 is useful when the user wants to replace a song with another
632 one. Passing NULL uses the currently active song.
634 @{"XMSNG_AddToList" LINK "xmodule.h/File" 205} - (@{"struct SongInfo" LINK "songclass.h/File" 284} *) Add the song to the song list.
635 When a song is being added to the list, a shared lock is
636 obtained on it to prevent other tasks from modifying (or even
637 remove) the song before you can do your job on it. IT IS YOUR
638 DUTY TO UNLOCK THE SONG as soon as you are done modifying it.
639 Passing NULL adds the song on the head of the list, while -1
640 (~0) will add it to the end of the SongList. Passing in a
641 pointer to another song which is already in the list, will
642 add the new song _after_ the latter.
643 (Default is not adding the song).
645 @{"XMSNG_Loader" LINK "xmodule.h/File" 207} - (@{"struct XMHook" LINK "xmodule.h/File" 92} *) Disables automatic format
646 checking and forces loading the module with the given
647 loader. (Defaults to NULL).
649 @{"XMSNG_FileHandle" LINK "xmodule.h/File" 208} - (BPTR) pointer to an open AmigaDOS
650 FileHandle to read the module from. The file must
651 already be positioned over the beginning of the module data.
652 NOTE: Even if this tag is passed, the fileName parameter is
653 still used to fill in the SongName field in case it is
654 missing inside the module AND the filesystem does not
655 support the ACTION_EXAMINE_FH packet.
656 NOTE: Some loaders may require a fully seekable file, so be
657 careful when using pipes.
658 NOTE: automatic data decompression is not possible when
659 @{"XMSNG_FileHandle" LINK "xmodule.h/File" 208} is passed.
662 XMSNG_IFFHandle - (BPTR) pointer to an already initialized
663 IFFHandle to read the module from. The IFF must
664 already be positioned over the beginning of the module FORM.
665 Even if this tag is passed, the fileName parameter is still
666 used to fill in the SongName field in case it is missing
668 NOTE: The iffparse.library can deal with non-seekable files,
669 but some loaders may require a fully seekable file, so be
670 careful when using pipes.
671 NOTE: automatic file decompression is not possible when
672 XMSNG_IFFHandle is passed.
675 @{"XMSNG_Active" LINK "xmodule.h/File" 209} - (BOOL) Makes this song the active one. This tag is
676 considered only if the @{"XMSNG_AddToList" LINK "xmodule.h/File" 205} tag is also passed.@{b}
679 songInfo - Pointer to the newly allocated SongInfo structure, or
680 NULL for failure. This function will not fail if the module is
681 partially corrupted. Anyway, the returned SongInfo will always
682 be valid. You can check IoErr() to know if there were problems.@{b}
685 /* Load a song and add it to the SongList */
686 si = xmLoadSongTags (file, NULL,
687 @{"XMSNG_AddToList" LINK "xmodule.h/File" 205}, (@{"struct SongInfo" LINK "songclass.h/File" 284} *)~0,
690 /* Check for errors even if si is not NULL */
693 /* Release Semaphore got by xmLoadSong() */
694 if (si) ReleaseSemaphore (&si->Lock);@{b}
697 @{"xmAddSongA()" LINK "xmAddSongA"}, @{"xmIdentifyModule()" LINK "xmIdentifyModule"}
700 @NODE "xmLockActiveSong" "xmodule/xmLockActiveSong()"
704 xmLockActiveSong -- Obtains an lock on the active song@{b}
707 song = xmLockActiveSong(mode);
710 @{"struct SongInfo" LINK "songclass.h/File" 284} *@{"xmActivateSong" LINK "xmActivateSong"}(UWORD);@{b}
713 Obtains an exclusive or shared lock on the active song,
714 waiting if needed. This call is a shortcut to:
716 ObtainSemaphoreShared (&XModuleBase->xm_BaseLock);
717 ObtainSemaphore[Shared] (&XModuleBase->xm_CurrentSong.Lock);
718 ReleaseSemaphore (&XModuleBase->xm_BaseLock);
720 To unlock a song obtained in this way, you just need to
721 ReleaseSemaphore() it.
723 You MUST always lock a song before you even think to
724 read from -or write to- its data!@{b}
727 mode - one of SM_SHARED or SM_EXCLUSIVE.@{b}
730 song - Pointer to the song which *was* active at the time
731 you called xmLockActiveSong(). The song will be
732 locked for you. The result will be NULL if no song
736 Please be careful if you call this function while holding
737 locks on other songs. Doing so, you run the risk of causing
739 This function does only lock the song; it is NOT guaranteed
740 that it will remain the active one.@{b}
745 @NODE "xmProcessSongA" "xmodule/xmProcessSongA()"
749 xmProcessSongA -- Performs complex processing on a song
750 xmProcessSong -- Varargs stub for xmProcessSongA()@{b}
753 result = xmProcessSongA(si, reserved, tagList)
756 LONG xmProcessSongA(@{"struct SongInfo" LINK "songclass.h/File" 284} *,void *,struct TagItem *);
759 result = xmProcessSong(si, reserved, tag1, ...)
761 LONG xmProcessSongA(@{"struct SongInfo" LINK "songclass.h/File" 284} *,void *,LONG,...);@{b}
764 Performs complex processing operations on a song.@{b}
767 si - pointer to the song to be processed.
768 reserved - Reserved for future use.
769 tagList - List of arguments. See below for possible tags.@{b}
772 The result depends on the kind of operation done. For most
773 operations, it's value will be 0 to indicate success and
774 an AmigaDOS error code which indicates the cause for failure.@{b}
777 @{"XMSNG_Optimize" LINK "xmodule.h/File" 213} - (LONG). Tries to reduce the song size by removing
778 all unused data. Possible optimizations are:
779 - @{"XMOF_REM_UNUSED_PATTERNS" LINK "xmodule.h/File" 221}
780 - @{"XMOF_REM_DUP_PATTERNS" LINK "xmodule.h/File" 222}
781 - @{"XMOF_CUT_PATTERNS" LINK "xmodule.h/File" 227}
782 - @{"XMOF_REM_UNUSED_INSTRS" LINK "xmodule.h/File" 223}
783 - @{"XMOF_CUT_INSTR_LOOPS" LINK "xmodule.h/File" 225}
784 - @{"XMOF_CUT_INSTR_TAILS" LINK "xmodule.h/File" 226}
785 - @{"XMOF_DEFAULT" LINK "xmodule.h/File" 220}
786 @{"XMOF_DEFAULT" LINK "xmodule.h/File" 220} will select all the optimizations choosen by
787 the user in addition to the ones specified with the other flags.
789 @{"XMSNG_RemapInstruments" LINK "xmodule.h/File" 214} - (BOOL) Performs instruments remapping.
791 @{"XMSNG_LimitPatterns" LINK "xmodule.h/File" 215} - (UWORD,UWORD) Limits the length all the
792 patterns inside a minimum and maximum value. The upper 16bits
793 of the argument are the minimum value, the lower ones are
794 the maximum value. Patterns outside this limits will be grown
795 or split as appropriate.
797 @{"XMSNG_Join" LINK "xmodule.h/File" 216} - (@{"struct SongInfo" LINK "songclass.h/File" 284} *) - Joins the song with another one.
799 @{"XMSNG_Merge" LINK "xmodule.h/File" 217} - (@{"struct SongInfo" LINK "songclass.h/File" 284} *) - Merges the song with another one.@{b}
802 In order to process a song, you should have exclusive access to
803 it. Always obtain a lock before you call this function on
807 @NODE "xmRemHook" "xmodule/xmRemHook()"
811 xmRemHook -- Removes an XModule Hook@{b}
817 void xmRemHook(@{"struct XMHook" LINK "xmodule.h/File" 92} *);@{b}
820 Removes an XModule Hook, calls its RemoveHookFunc() and then
821 frees its memory.@{b}
824 xmHook - pointer to the hook to be removed.@{b}
827 @{"xmAddHook()" LINK "xmAddHook"}
830 @NODE "xmRemInstrument" "xmodule/xmRemInstrument()"
834 xmRemInstrument -- Removes an instrument from a song@{b}
837 xmRemInstrument(si, instrNum)
840 void xmRemInstrument(@{"struct SongInfo" LINK "songclass.h/File" 284} *,LONG);@{b}
843 Removes an instrument from a song by calling the @{"SNGM_REMINSTRUMENT" LINK "songclass.h/File" 34}
847 si - pointer to the song to which the instrument should be removed.
848 mum - Number of the instrument to be removed.@{b}
851 In order to remove instruments, you should have exclusive access to
852 the song. Always obtain a lock before you call this function on
856 @{"xmAddInstrumentA()" LINK "xmAddInstrumentA"}, @{"songclass" LINK "songclass/MAIN"}/SNGM_REMINSTRUMENT
859 @NODE "xmRemPattern" "xmodule/xmRemPattern()"
863 xmRemPattern -- Removes a pattern from a song@{b}
866 xmRemPattern(si, pattNum, replaceWith)
869 void xmRemPattern(@{"struct SongInfo" LINK "songclass.h/File" 284} *,LONG,LONG);@{b}
872 Removes a pattern from a song by calling the @{"SNGM_REMPATTERN" LINK "songclass.h/File" 31} method.@{b}
875 si - pointer to the song to which the pattern should be removed.
876 mum - Number of the pattern to be removed.
877 replaceWith - What to put in the song sequence in place of the
881 In order to remove patterns, you should have exclusive access to
882 the song. Always obtain a lock before you call this function on
886 @{"xmAddPatternA()" LINK "xmAddPatternA"}, @{"songclass" LINK "songclass/MAIN"}/SNGM_REMPATTERN
889 @NODE "xmRemSong" "xmodule/xmRemSong()"
893 xmRemSong -- Remove a song from the song list@{b}
896 success = xmRemSong(songInfo);
899 ULONG xmRemSong(@{"struct SongInfo" LINK "songclass.h/File" 284} *);@{b}
902 Removes a song from the public song list. It is safe to call this
903 function even if the song has not been added to the song list. If
904 the passed SongInfo is the active one, another song will be
905 selected automatically.@{b}
908 songInfo - song to be removed. If NULL, this function will take
912 success - Will be 0 for failure, in which case the song will
913 not be removed from the song list. Currently,
914 xmRemSong() will never fail.@{b}
917 In order to remove a song, you must first obtain an exclusive
920 The song list is also protected from multiple task access by
921 a SignalSemaphore. This call will wait if the song list has
922 been locked by another task. Beware of deadlock conditions!@{b}
925 @{"xmAddSongA()" LINK "xmAddSongA"}
928 @NODE "xmSaveModuleA" "xmodule/xmSaveModuleA()"
932 xmSaveModuleA -- Saves a module to the specified file format
933 xmSaveModule -- Varargs stub for xmSaveModuleA@{b}
936 error = xmSaveModuleA(songInfo, fileName, saver, tagList)
939 LONG xmSaveModuleA(@{"struct SongInfo" LINK "songclass.h/File" 284} *,STRPTR,@{"struct XMHook" LINK "xmodule.h/File" 92} *,
943 error = xmSaveModule(songInfo, fileName, saver, tag1,...)
945 LONG xmSaveModule(@{"struct SongInfo" LINK "songclass.h/File" 284} *,STRPTR,@{"struct XMHook" LINK "xmodule.h/File" 92} *,
949 Saves songInfo to fileName using the specified saver.@{b}
952 songInfo - Song to save.
953 fileName - AmigaDOS filename to write the song to.
954 saver - Pointer to the saver to use. Pass NULL to use
955 the default saver.@{b}
958 No tags are defined for this call.@{b}
961 error - RETURN_OK for success, or any other AmigaDOS error code
962 to mean failure. In particular, RETURN_WARN indicates that
963 something went wrong, but the song is still ok. The special
964 error code @{"ERROR_IOERR" LINK "xmodule.h/File" 194} means that some dos.library
965 call (e.g.: Read()) failed. In the latter case, the
966 AmigaDOS IoErr() value will be set to explain the specific
967 cause of the problem.@{b}
972 @NODE "xmSetInstrumentA" "xmodule/xmSetInstrumentA()"
976 xmSetInstrumentA -- Sets an instrument's attributes
977 xmSetInstrument -- Varargs stub for xmSetInstrumentA@{b}
980 success = xmSetInstrumentA(si, instrNum, tagList)
983 ULONG xmSetInstrumentA(@{"struct SongInfo" LINK "songclass.h/File" 284} *,LONG,
987 success = xmSetInstrument(si,instrNum,tag1,...)
989 ULONG xmSetInstrument(@{"struct SongInfo" LINK "songclass.h/File" 284} *,LONG,LONG,...);@{b}
992 Sets an instrument's attributes by calling the @{"SNGM_SETINSTRUMENT" LINK "songclass.h/File" 33}
996 si - pointer to the song which contains the instrument to be set.
997 tagList - instrument attributes to set. See @{"SNGM_SETINSTRUMENT" LINK "songclass.h/File" 33}
998 for possible tags.@{b}
1001 non zero for success.@{b}
1004 In order to set instruments' attributes, you should have
1005 exclusive access to the song. Always obtain a lock before
1006 you call this function on public songs.@{b}
1009 @{"xmAddInstrument()" LINK "xmAddInstrumentA"}, @{"songclass" LINK "songclass/MAIN"}/SNGM_SETINSTRUMENT
1012 @NODE "xmSetPatternA" "xmodule/xmSetPatternA()"
1016 xmSetPatternA -- Sets pattern attributes
1017 xmSetPattern -- Varargs stub for xmSetPatternA@{b}
1020 success = xmSetPatternA(si, pattNum, tagList)
1023 ULONG xmSetPatternA(@{"struct SongInfo" LINK "songclass.h/File" 284} *,ULONG,struct TagItem *);
1026 success = xmSetPattern (si,pattNum,tag1,...)
1028 ULONG xmSetPattern(@{"struct SongInfo" LINK "songclass.h/File" 284} *,ULONG,LONG Tag1,...);@{b}
1031 Sets attributes of a pattern by calling the @{"SNGM_SETPATTERN" LINK "songclass.h/File" 30} method.@{b}
1034 si - pointer to the song which contains the pattern to be set.
1035 tagList - list of attributes to set. See @{"SNGM_SETPATTERN" LINK "songclass.h/File" 30} for
1039 Non zero for success@{b}
1042 In order to set patterns attributes, you should have exclusive
1043 access to the song. Always obtain a lock before you call this
1044 function on public songs.@{b}
1047 @{"xmAddPattern()" LINK "xmAddPatternA"}, @{"songclass" LINK "songclass/MAIN"}/SNGM_SETPATTERN
1050 @NODE "xmSetSongLen" "xmodule/xmSetSongLen()"
1054 xmSetSongLen -- Set the number of song positions@{b}
1057 sequence = xmSetSongLen(songInfo, length)
1060 UWORD *xmSetSongLen(@{"struct SongInfo" LINK "songclass.h/File" 284} *, UWORD);@{b}
1063 Allocates space in the song for a sequence table of the given
1064 length. If no sequence exists yet, a new one is allocated.
1065 Increasing the song length may require the sequence table to be
1066 expanded, in which case it will be re-allocated and the old sequence
1067 entries will be copied. Decreasing the song length could also cause
1068 a reallocation of the sequence table if the size drops down enough.
1069 Setting the song length to 0 will free the sequence table and return
1073 songInfo - pointer to a SongInfo structure.
1074 length - new length of song sequence table.@{b}
1077 This function will also adjust the CurrentPos field if it is found
1078 beyond the song end@{b}
1081 This funtion is quite useless because all it does is setting the
1082 @{"SNGA_Length" LINK "songclass.h/File" 88} attribute in the song object. Setting the @{"SNGA_Length" LINK "songclass.h/File" 88}
1083 attribute yourself is easier and faster if you are already setting
1084 other attributes in the same song.@{b}
1087 Pointer to the newly allocated sequence table or NULL for failure,
1088 in which case the previous sequence table is left untouched.