6 xmodule/xmAddInstrumentA
11 xmodule/xmDisplayMessage
12 xmodule/xmDisplayProgress
13 xmodule/xmIdentifyModule
15 xmodule/xmLockActiveSong
16 xmodule/xmProcessSongA
18 xmodule/xmRemInstrument
22 xmodule/xmSetInstrumentA
25 \fxmodule/--background-- xmodule/--background--
28 The xmodule.library is an API that provides access to the XModule
29 song management engine, as well as other general pourpose
30 services. Hooks and external applications can use this library
31 to create, load, save and modify songs.
33 The xmodule.library does not exist as a stand alone shared libray.
34 Instead, it's code is contained inside the main XModule executable
35 (altrough it's logically independant from the rest of the XModule
38 XModule adds the xmodule.library to the exec libray list at
39 startup time, unless it finds one already in the list (this might
40 happen when multiple copies of XModule are running at the same
44 The xmodule.library maintains a list of public songs which can be
45 used by all applications which opened the library. Each song in
46 the list is protected from multiple task access by a
47 SignalSemaphore, and whole list is also protected by another
48 semaphore. The locking mechanism is very simple: before you can
49 access a song you must obtain its semaphore, and you must release
50 it as soon as you are done with it. If you are locking a song to
51 just to read some information (i.e.: you don't want to modify
52 anything), you should obtain a shared lock instead of an exclusive
53 one. The list must be locked whenever you want to add or remove
54 a song, or when you scan it in any way.
56 Since public songs could be modified or even deleted by other
57 tasks, do not make your songs public unless your code is smart
58 enough to handle all possible situations.
62 Actually, most modular programs call them `modules', but it would
63 have created a lot of confusion with a program like XModule :-).
65 Hooks are programs that add some kind of functionality
66 to XModule. External hook files are standard shared libraries
67 which will open the xmodule.library when they are loaded and
68 call xmAddHookA() to add themselves to a list of hooks maintained
71 Currently, XModule supports two kinds of hooks: loaders and
72 savers. Loader hooks can also provide a function which
73 identifies a particular module format.
75 An external hook libray may also contain several hooks.
76 Putting a loader and a saver for one particolar format together
77 in one libray is generally a good idea, while making a hook
78 with hundereds of loaders and savers isn't a good move because
79 it makes the whole concept of external hooks quite useless.
80 Grouping different versions or variants of one format together
81 in one external hook is acceptable.
84 songclass/--background--, exec/ObtainSemaphore()
86 \fxmodule/xmActivateSong xmodule/xmActivateSong
89 xmActivateSong -- Makes a song the active one
92 success = xmActivateSong(songInfo);
95 ULONG xmActivateSong(struct SongInfo *);
98 Makes the passed song the currently active one. It's pointer
99 will be stored in the public song list and most actions
100 will happen on this song by default.
103 songInfo - song to be activated. If NULL, this function will
107 success - Will be 0 for failure, in which case the song will
108 not be removed from the song list. Currently,
109 xmActivateSong() will never fail.
112 In order to activate a song, you must own a shared lock
113 on it. Please do not hog this lock for a long time when
114 xmActivateSong() returns, because most internal routines
115 try to lock the current song before taking any action.
119 \fxmodule/xmAddHook xmodule/xmAddHook
122 xmAddHookA -- Creates a new XModule Hook
123 xmAddHook -- Varargs stub for xmAddHookA
126 hook = xmAddHookA(tagList)
129 struct XMHook *xmAddHookA(struct TagItem *);
132 hook = xmAddHook(Tag1,...)
134 struct XMHook *xmAddHook(ULONG,...);
137 Creates a new XMHook structure and fills it in with data supplied
138 with the TagList. Adds the newly created Hook to the appropriate
142 tagList - pointer to a tag list specifying how to initialize the
146 XMHOOK_Type - (ULONG) Defines the pourpose of this hook. Possible
147 values are currently NT_XMLOADER and NT_XMSAVER. (This
150 XMHOOK_Name - (STRPTR) ti_Data contains a short name for the
151 hook (e.g: "SoundTracker"). This name will appear in the
152 Savers list if this hook is a saver and will be passed as an
153 argument for some ARexx commands, so please use a single
154 word name. (This tag is REQUIRED).
156 XMHOOK_Priority - (BYTE) Priority to give to this hook. Hooks
157 with higher priorities will be used before lower priority
158 ones and will come first in lists shown to the user. Valid
159 range is -128..+127, but please restrict to a -20..+20
160 interval for normal cases. (Defaults to 0).
162 XMHOOK_Descr - (STRPTR) Verbose description of the hook
163 (without newlines). (Defaults to NULL).
165 XMHOOK_Author - (STRPTR) Author's name. Please, just put
166 your full name here; no greetings, copyright notices,
167 etc. (Defaults to NULL).
169 XMHOOK_ID - (ULONG) This is a unique, IFF-style identifier for
170 the format. If the format is an IFF format, it must be the
171 same of the FORM ID. (Defaults to 0, this tag is required
172 for IFF loaders and savers).
174 XMHOOK_Flags - (ULONG) Sets miscellaneous flags for this hook.
175 See xmodule.h for possible flags.
177 XMHOOK_LibraryBase - (struct Library *) Pointer to the library
178 base for external hooks. This pointer will be used to open
179 the library when the hook is created and to close it when
180 the hook is deleted. If you do not pass this tag, you must
181 find some other way to keep your code in memory until one
182 or more of your hooks are active. XModule will close your
183 library just after calling the SetupXMHook() function.
186 XMHOOK_UserData - (APTR) ti_Data will be stored in the
187 xmh_UserData field of the XMHook structure. This field can
188 come andy to store private data. (Defaults to NULL).
190 XMHOOK_RemoveHookFunc - (APTR) Pointer to a function which will be
191 called upon removing the hook. This function can be used to
192 free any private resources allocated by the hook when it was
193 created. The template for the function is:
195 void RemoveHookFunc (struct XMHook *hook);
198 XMHOOK_LoadModFunc - (APTR) Pointer to the hook function which
199 loads a module. The template for the function is:
201 LONG LoadModFunc (BPTR fileHandle, struct SongInfo *song,
203 struct XMHook *loader);
206 `fileHandle' is an open file to load the module from. The
207 caller will take care to close it for you. The loader should
208 return RETURN_OK for success, or any other AmigaDOS error
209 code to mean failure. In particular, RETURN_WARN indicates
210 that something went wrong, but the song is ok. The special
211 error code ERROR_IOERR can be used when some dos.library
212 call (e.g.: Read()) failed. In the latter case, the
213 AmigaDOS IoErr value should be set to explain the specific
214 cause of the problem.
215 (This tag is required by all NT_XMLOADER type hooks).
217 XMHOOK_SaveModFunc - (APTR) Pointer to the hook function which
218 saves a module. The template for the function is:
220 LONG SaveModFunc (BPTR fileHandle, struct SongInfo *song,
222 struct XMHook *saver);
225 fileHandle is an open file to save the module to. The caller
226 will take care to close it for you. The saver should return
227 RETURN_OK for success, or any other AmigaDOS error code to
228 mean failure. In particular, RETURN_WARN indicates that
229 something went wrong, but the song is ok. The special
230 error code ERROR_IOERR can be used when some dos.library
231 call (e.g.: Read()) failed. In the latter case, the
232 AmigaDOS IoErr value should be set to explain the specific
233 cause of the problem.
234 (This tag is required by all NT_XMSAVER type hooks).
237 XMHOOK_IdentifyModFunc - (APTR) Pointer to the hook function
238 which identifies a module format. The template for the
241 struct XMHook *IdentifyModFunc (BPTR fileHandle,
243 struct XMHook *hook,struct TagItem *tagList);
246 fileHandle is an open file to try the identification on. The
247 caller will take care to close it. NOTE: Do not make assumptions
248 on the initial file position (e.g: seek yourself to position 0
249 if you need to). This funtion should return a pointer to a valid
250 loader (usually the one passed in) if the format is recognized,
251 NULL otherwhise. (This tag is required by all NT_XMLOADER type
255 hook - Pointer to the newly allocated XMHook structure, or
259 xmRemHook(), xmIdentifyModule(), xmLoadSong(), xmSaveSong()
261 \fxmodule/xmAddInstrumentA xmodule/xmAddInstrumentA
264 xmAddInstrumentA -- Adds a instrument to a song
265 xmAddInstrument -- Varargs stub for xmAddInstrumentA
268 instrument = xmAddInstrumentA(si, instrNum, tagList)
271 struct Instrument *xmAddInstrumentA(struct SongInfo *,LONG,
275 instrument = xmAddInstrument(si,instrNum,tag1,...)
277 struct Instrument *xmAddInstrument(struct SongInfo *,LONG,LONG,...);
280 Adds an instrument to a song by calling the SNGM_ADDINSTRUMENT method
284 si - pointer to the song to which the instrument should be added.
285 tagList - optional TagList. See SNGM_ADDINSTRUMENT for possible tags
289 Pointer to the new instrument or NULL for failure.
292 In order to add instruments, you should have exclusive access to
293 the song. Always obtain a lock before you call this function on
297 xmRemInstrument(), songclass/SNGM_REMINSTRUMENT
299 \fxmodule/xmAddPatternA xmodule/xmAddPatternA
302 xmAddPatternA -- Adds a pattern to a song
303 xmAddPattern -- Varargs stub for xmAddPatternA
306 pattern = xmAddPatternA(si, tagList)
309 struct Pattern *xmAddPatternA(struct SongInfo *,struct TagItem *);
312 pattern = xmAddPattern (si,tag1,...)
314 struct Pattern *xmAddPattern(struct SongInfo *,LONG Tag1,...);
317 Adds a pattern to a song by calling the SNGM_ADDPATTERN method.
320 si - pointer to the song to which the pattern should be added.
321 tagList - optional TagList. See SNGM_ADDPATTERN for possible tags.
324 Pointer to the new pattern or NULL for failure.
327 In order to add patterns, you should have exclusive access to
328 the song. Always obtain a lock before you call this function on
332 xmRemPattern(), songclass/SNGM_ADDPATTERN
334 \fxmodule/xmAddSongA xmodule/xmAddSongA
337 xmAddSongA -- Add a song to the song list
338 xmAddSong -- Varargs stub for xmAddSongA
341 success = xmAddSongA(songInfo,position,tagList);
344 ULONG xmAddSongA(struct SongInfo *,struct SongInfo *,
348 success = xmAddSong(songInfo,position,tag1,...);
350 ULONG xmAddSong(struct SongInfo *,struct SongInfo *,
354 Adds a song to the public song list. Trying to add a song
358 songInfo - song to be added. Passing a NULL pointer is safe.
359 position - Position to add the song in. Passing NULL adds the
360 song in the head of the list, while ~0 adds it in the tail.
361 passing a pointer to a SongInfo already in the list inserts
362 the first song _after_ the other one.
363 tagList - pointer to a TagList for more arguments.
366 XMSNG_Active - (BOOL) Makes this song the active one. The
367 default is to just add the song without activating it.
370 success - Will be 0 for failure, in which case the song will
371 not be added to the songs list. Currently, xmAddSongA()
375 The song list is protected from multiple tasks access by a
376 SignalSemaphore in XModuleBase. This call will wait if the
377 song list has been locked by another task. Beware of deadlock
383 \fxmodule/xmCreateSong xmodule/xmCreateSong
386 xmCreateSongA -- Create and initialize a new SongInfo structure
387 xmCreateSong -- Varargs stub for xmCreateSongA
390 songInfo = xmCreateSongA(tagList);
393 struct SongInfo *xmCreateSongA(struct TagItem *);
396 songInfo = xmCreateSong(Tag1,...);
398 struct SongInfo *xmCreateSong(ULONG,...);
401 Allocates and initializes a new SongInfo structure. The song
402 can then be added to the song list via xmAddSongA(), in which
403 case, it is no longer required to free it with xmDeleteSong().
406 tagList - pointer to an optional tag list specifying how to
407 initialize the SongInfo structure.
410 SNGA_DefaultTracks - Sets the default number of pattern tracks for
411 the song. Defaults to 4.
413 SNGA_DefaultPattLen - Sets the default number of pattern lines for
414 the song. Defaults to 64.
416 SNGA_ReadyToUse - Adds one pattern and one position to the song.
419 XMSNG_AddToList - (struct SongInfo *) Add the song to the song list.
420 When a song is being added to the list, a shared lock is
421 obtained on it to prevent other tasks from modifying (or even
422 remove) the song before you can do your job on it. IT IS YOUR
423 DUTY TO UNLOCK THE SONG as soon as you are done modifying it.
424 Passing NULL adds the song on the head of the list, while -1
425 (~0) will add it to the end of the SongList. Passing in a
426 pointer to another song which is already in the list, will
427 add the new song _after_ the latter.
428 (Default is not adding the song).
430 XMSNG_Active - (BOOL) Makes this song the active one. This tag is
431 considered only if the XMSNG_AddToList tag is also passed.
434 songInfo - pointer to the newly allocated SongInfo structure, or
438 xmDeleteSong(), xmAddSongA()
440 \fxmodule/xmDeleteSong xmodule/xmDeleteSong
443 xmDeleteSong -- Deletes a song
446 xmDeleteSong(songInfo)
449 void xmDeleteSong(struct SongInfo *);
452 Deletes a song and all the items attached to it (patterns,
453 instruments, etc.). This call will also remove the song from
454 the song list if it had been added to it.
457 songInfo - pointer to the SongInfo structure to be deleted.
458 Passing a NULL pointer is harmless.
461 In order to delete a song which has been added to the public
462 song list, you must first obtain an exclusive lock on it to
463 prevent other tasks from walking on it while you are freeing
464 it's data structures. The semaphore does NOT need to be
465 relinquished, because the SongInfo structure won't exist any
466 more when this call returns.
469 xmCreateSong(), xmRemSong()
471 \fxmodule/xmDisplayMessage xmodule/xmDisplayMessage
474 xmDisplayMessageA -- Displays a message to the user
475 xmDisplayMessage -- Varargs stub for xmDisplayMessageA()
478 xmDisplayMessageA(level, message, args)
481 void xmDisplayMessageA(ULONG,APTR,LONG *);
484 xmDisplayMessage(level, message, ...)
486 void xmDisplayMessage(ULONG,APTR,...);
489 Outputs a string in the XModule log window or in the 'action' field
490 of the progress indicator. The string is printf-formatted before
494 level - a number from 0 to 7 which indicates the importance of the
495 message. 7 is used for very annoying messages (eg: debug output)
497 0 for very important things (eg: disaster).
498 If you set the XMDMF_USECATALOG bit in the level parameter, you
499 can pass a catalog string number instead of a pointer to a string
501 Specifying XMDMF_ACTION, the message will be put in the 'action'
502 field of the progress indicator.
503 If the flag XMDMF_DOSFAULT is specified, a Fault() output is
504 formatted using the message as an header. In this case, the
505 level parameter takes another meaing: The lower word can contain
506 an AmigaDOS error code. If it is 0, IoErr() will be used to get
508 message - pointer to a string or catalog message number,
509 when the XMDMF_USECATALOG flag is set.
510 args - arguments for formatting.
513 xmDisplayMessage (XMDMF_ALERT,
514 "The application `%s' fucked up Windoze95 because %s.",
515 "(unknown name)", "an error occurred");
517 xmDisplayMessage (XMDMF_USE_CATALOG | XMDMF_COMMENT,
518 MSG_LIFE_UNIVERSE_AND_ALLTHAT, 42, "Fortytwo", "For tea too");
520 xmDisplayMessageA (XMDMF_ACTION | XMDMF_USECATALOG,
521 MSG_READING_COMICS, NULL);
523 xmDisplayMessage (XMDMF_DOSFAULT | XMDMF_USECATALOG,
524 MSG_CANT_LOAD_MODULE, ModuleName);
529 \fxmodule/xmDisplayProgress xmodule/xmDisplayProgress
532 xmDisplayProgress -- Uptdates the progress bar indicator
535 abort = xmDisplayProgress(done, total)
538 LONG xmDisplayMessageA(ULONG,ULONG);
541 Updates the position of the fuel gauge in the progress window to
542 show the progress of an operation. Additionally, it checks for
546 done - a number which indicates how much of the work has
547 been already completed
548 total - Total number of operations to do.
551 0 for success, ERROR_BREAK if user abort was detected. You should
552 always check this return code to abort what you were doing.
554 \fxmodule/xmIdentifyModule xmodule/xmIdentifyModule
557 xmIdentifyModule -- Returns the type of a module
560 loader = xmIdentifyModule(fh, tagList)
563 struct XMHook *xmIdentifyModule(BPTR,struct TagItem *);
566 Finds out a loader which is able to read the given module.
569 fh - AmigaDOS FileHandle to examine.
570 tagList - Additional parameters. Leave it NULL for now.
573 loader - Pointer to the first loader which knows how to load this
574 module, or NULL otherwise.
577 Before you call this function, you must first obtain a lock on the
578 loaders list to protect yourself from other tasks which might remove
579 the returned loader before you can actually use it.
583 \fxmodule/xmLoadModuleA xmodule/xmLoadModuleA
586 xmLoadModuleA -- Loads a module and converts it in XModule format
587 xmLoadModule -- Varargs stub for xmLoadModuleA
590 songInfo = xmLoadModuleA(fileName,tagList)
593 struct SongInfo *xmLoadModuleA(STRPTR,struct TagItem *);
596 songInfo = xmLoadModule(fileName,tag,...)
598 struct SongInfo *xmLoadModule(STRPTR,LONG,...);
601 Loads fileName using the correct module loader.
604 fileName - File to read. Can be NULL if the XMSNG_FileHandle
606 tagList - Additional parameters (see below). Can be NULL.
609 XMSNG_OldSong - ti_Data is the pointer to a SongInfo which will be
610 freed as soon as the module format has been determined. This
611 is useful when the user wants to replace a song with another
612 one. Passing NULL uses the currently active song.
614 XMSNG_AddToList - (struct SongInfo *) Add the song to the song list.
615 When a song is being added to the list, a shared lock is
616 obtained on it to prevent other tasks from modifying (or even
617 remove) the song before you can do your job on it. IT IS YOUR
618 DUTY TO UNLOCK THE SONG as soon as you are done modifying it.
619 Passing NULL adds the song on the head of the list, while -1
620 (~0) will add it to the end of the SongList. Passing in a
621 pointer to another song which is already in the list, will
622 add the new song _after_ the latter.
623 (Default is not adding the song).
625 XMSNG_Loader - (struct XMHook *) Disables automatic format
626 checking and forces loading the module with the given
627 loader. (Defaults to NULL).
629 XMSNG_FileHandle - (BPTR) pointer to an open AmigaDOS
630 FileHandle to read the module from. The file must
631 already be positioned over the beginning of the module data.
632 NOTE: Even if this tag is passed, the fileName parameter is
633 still used to fill in the SongName field in case it is
634 missing inside the module AND the filesystem does not
635 support the ACTION_EXAMINE_FH packet.
636 NOTE: Some loaders may require a fully seekable file, so be
637 careful when using pipes.
638 NOTE: automatic data decompression is not possible when
639 XMSNG_FileHandle is passed.
642 XMSNG_IFFHandle - (BPTR) pointer to an already initialized
643 IFFHandle to read the module from. The IFF must
644 already be positioned over the beginning of the module FORM.
645 Even if this tag is passed, the fileName parameter is still
646 used to fill in the SongName field in case it is missing
648 NOTE: The iffparse.library can deal with non-seekable files,
649 but some loaders may require a fully seekable file, so be
650 careful when using pipes.
651 NOTE: automatic file decompression is not possible when
652 XMSNG_IFFHandle is passed.
655 XMSNG_Active - (BOOL) Makes this song the active one. This tag is
656 considered only if the XMSNG_AddToList tag is also passed.
659 songInfo - Pointer to the newly allocated SongInfo structure, or
660 NULL for failure. This function will not fail if the module is
661 partially corrupted. Anyway, the returned SongInfo will always
662 be valid. You can check IoErr() to know if there were problems.
665 /* Load a song and add it to the SongList */
666 si = xmLoadSongTags (file, NULL,
667 XMSNG_AddToList, (struct SongInfo *)~0,
670 /* Check for errors even if si is not NULL */
673 /* Release Semaphore got by xmLoadSong() */
674 if (si) ReleaseSemaphore (&si->Lock);
677 xmAddSongA(), xmIdentifyModule()
679 \fxmodule/xmLockActiveSong xmodule/xmLockActiveSong
682 xmLockActiveSong -- Obtains an lock on the active song
685 song = xmLockActiveSong(mode);
688 struct SongInfo *xmActivateSong(UWORD);
691 Obtains an exclusive or shared lock on the active song,
692 waiting if needed. This call is a shortcut to:
694 ObtainSemaphoreShared (&XModuleBase->xm_BaseLock);
695 ObtainSemaphore[Shared] (&XModuleBase->xm_CurrentSong.Lock);
696 ReleaseSemaphore (&XModuleBase->xm_BaseLock);
698 To unlock a song obtained in this way, you just need to
699 ReleaseSemaphore() it.
701 You MUST always lock a song before you even think to
702 read from -or write to- its data!
705 mode - one of SM_SHARED or SM_EXCLUSIVE.
708 song - Pointer to the song which *was* active at the time
709 you called xmLockActiveSong(). The song will be
710 locked for you. The result will be NULL if no song
714 Please be careful if you call this function while holding
715 locks on other songs. Doing so, you run the risk of causing
717 This function does only lock the song; it is NOT guaranteed
718 that it will remain the active one.
722 \fxmodule/xmProcessSongA xmodule/xmProcessSongA
725 xmProcessSongA -- Performs complex processing on a song
726 xmProcessSong -- Varargs stub for xmProcessSongA()
729 result = xmProcessSongA(si, reserved, tagList)
732 LONG xmProcessSongA(struct SongInfo *,void *,struct TagItem *);
735 result = xmProcessSong(si, reserved, tag1, ...)
737 LONG xmProcessSongA(struct SongInfo *,void *,LONG,...);
740 Performs complex processing operations on a song.
743 si - pointer to the song to be processed.
744 reserved - Reserved for future use.
745 tagList - List of arguments. See below for possible tags.
748 The result depends on the kind of operation done. For most
749 operations, it's value will be 0 to indicate success and
750 an AmigaDOS error code which indicates the cause for failure.
753 XMSNG_Optimize - (LONG). Tries to reduce the song size by removing
754 all unused data. Possible optimizations are:
755 - XMOF_REM_UNUSED_PATTERNS
756 - XMOF_REM_DUP_PATTERNS
758 - XMOF_REM_UNUSED_INSTRS
759 - XMOF_CUT_INSTR_LOOPS
760 - XMOF_CUT_INSTR_TAILS
762 XMOF_DEFAULT will select all the optimizations choosen by
763 the user in addition to the ones specified with the other flags.
765 XMSNG_RemapInstruments - (BOOL) Performs instruments remapping.
767 XMSNG_LimitPatterns - (UWORD,UWORD) Limits the length all the
768 patterns inside a minimum and maximum value. The upper 16bits
769 of the argument are the minimum value, the lower ones are
770 the maximum value. Patterns outside this limits will be grown
771 or split as appropriate.
773 XMSNG_Join - (struct SongInfo *) - Joins the song with another one.
775 XMSNG_Merge - (struct SongInfo *) - Merges the song with another one.
778 In order to process a song, you should have exclusive access to
779 it. Always obtain a lock before you call this function on
782 \fxmodule/xmRemHook xmodule/xmRemHook
785 xmRemHook -- Removes an XModule Hook
791 void xmRemHook(struct XMHook *);
794 Removes an XModule Hook, calls its RemoveHookFunc() and then
798 xmHook - pointer to the hook to be removed.
803 \fxmodule/xmRemInstrument xmodule/xmRemInstrument
806 xmRemInstrument -- Removes an instrument from a song
809 xmRemInstrument(si, instrNum)
812 void xmRemInstrument(struct SongInfo *,LONG);
815 Removes an instrument from a song by calling the SNGM_REMINSTRUMENT
819 si - pointer to the song to which the instrument should be removed.
820 mum - Number of the instrument to be removed.
823 In order to remove instruments, you should have exclusive access to
824 the song. Always obtain a lock before you call this function on
828 xmAddInstrumentA(), songclass/SNGM_REMINSTRUMENT
830 \fxmodule/xmRemPattern xmodule/xmRemPattern
833 xmRemPattern -- Removes a pattern from a song
836 xmRemPattern(si, pattNum, replaceWith)
839 void xmRemPattern(struct SongInfo *,LONG,LONG);
842 Removes a pattern from a song by calling the SNGM_REMPATTERN method.
845 si - pointer to the song to which the pattern should be removed.
846 mum - Number of the pattern to be removed.
847 replaceWith - What to put in the song sequence in place of the
851 In order to remove patterns, you should have exclusive access to
852 the song. Always obtain a lock before you call this function on
856 xmAddPatternA(), songclass/SNGM_REMPATTERN
858 \fxmodule/xmRemSong xmodule/xmRemSong
861 xmRemSong -- Remove a song from the song list
864 success = xmRemSong(songInfo);
867 ULONG xmRemSong(struct SongInfo *);
870 Removes a song from the public song list. It is safe to call this
871 function even if the song has not been added to the song list. If
872 the passed SongInfo is the active one, another song will be
873 selected automatically.
876 songInfo - song to be removed. If NULL, this function will take
880 success - Will be 0 for failure, in which case the song will
881 not be removed from the song list. Currently,
882 xmRemSong() will never fail.
885 In order to remove a song, you must first obtain an exclusive
888 The song list is also protected from multiple task access by
889 a SignalSemaphore. This call will wait if the song list has
890 been locked by another task. Beware of deadlock conditions!
895 \fxmodule/xmSaveModuleA xmodule/xmSaveModuleA
898 xmSaveModuleA -- Saves a module to the specified file format
899 xmSaveModule -- Varargs stub for xmSaveModuleA
902 error = xmSaveModuleA(songInfo, fileName, saver, tagList)
905 LONG xmSaveModuleA(struct SongInfo *,STRPTR,struct XMHook *,
909 error = xmSaveModule(songInfo, fileName, saver, tag1,...)
911 LONG xmSaveModule(struct SongInfo *,STRPTR,struct XMHook *,
915 Saves songInfo to fileName using the specified saver.
918 songInfo - Song to save.
919 fileName - AmigaDOS filename to write the song to.
920 saver - Pointer to the saver to use. Pass NULL to use
924 No tags are defined for this call.
927 error - RETURN_OK for success, or any other AmigaDOS error code
928 to mean failure. In particular, RETURN_WARN indicates that
929 something went wrong, but the song is still ok. The special
930 error code ERROR_IOERR means that some dos.library
931 call (e.g.: Read()) failed. In the latter case, the
932 AmigaDOS IoErr() value will be set to explain the specific
933 cause of the problem.
937 \fxmodule/xmSetInstrumentA xmodule/xmSetInstrumentA
940 xmSetInstrumentA -- Sets an instrument's attributes
941 xmSetInstrument -- Varargs stub for xmSetInstrumentA
944 success = xmSetInstrumentA(si, instrNum, tagList)
947 ULONG xmSetInstrumentA(struct SongInfo *,LONG,
951 success = xmSetInstrument(si,instrNum,tag1,...)
953 ULONG xmSetInstrument(struct SongInfo *,LONG,LONG,...);
956 Sets an instrument's attributes by calling the SNGM_SETINSTRUMENT
960 si - pointer to the song which contains the instrument to be set.
961 tagList - instrument attributes to set. See SNGM_SETINSTRUMENT
965 non zero for success.
968 In order to set instruments' attributes, you should have
969 exclusive access to the song. Always obtain a lock before
970 you call this function on public songs.
973 xmAddInstrument(), songclass/SNGM_SETINSTRUMENT
975 \fxmodule/xmSetPatternA xmodule/xmSetPatternA
978 xmSetPatternA -- Sets pattern attributes
979 xmSetPattern -- Varargs stub for xmSetPatternA
982 success = xmSetPatternA(si, pattNum, tagList)
985 ULONG xmSetPatternA(struct SongInfo *,ULONG,struct TagItem *);
988 success = xmSetPattern (si,pattNum,tag1,...)
990 ULONG xmSetPattern(struct SongInfo *,ULONG,LONG Tag1,...);
993 Sets attributes of a pattern by calling the SNGM_SETPATTERN method.
996 si - pointer to the song which contains the pattern to be set.
997 tagList - list of attributes to set. See SNGM_SETPATTERN for
1001 Non zero for success
1004 In order to set patterns attributes, you should have exclusive
1005 access to the song. Always obtain a lock before you call this
1006 function on public songs.
1009 xmAddPattern(), songclass/SNGM_SETPATTERN
1011 \fxmodule/xmSetSongLen xmodule/xmSetSongLen
1014 xmSetSongLen -- Set the number of song positions
1017 sequence = xmSetSongLen(songInfo, length)
1020 UWORD *xmSetSongLen(struct SongInfo *, UWORD);
1023 Allocates space in the song for a sequence table of the given
1024 length. If no sequence exists yet, a new one is allocated.
1025 Increasing the song length may require the sequence table to be
1026 expanded, in which case it will be re-allocated and the old sequence
1027 entries will be copied. Decreasing the song length could also cause
1028 a reallocation of the sequence table if the size drops down enough.
1029 Setting the song length to 0 will free the sequence table and return
1033 songInfo - pointer to a SongInfo structure.
1034 length - new length of song sequence table.
1037 This function will also adjust the CurrentPos field if it is found
1041 This funtion is quite useless because all it does is setting the
1042 SNGA_Length attribute in the song object. Setting the SNGA_Length
1043 attribute yourself is easier and faster if you are already setting
1044 other attributes in the same song.
1047 Pointer to the newly allocated sequence table or NULL for failure,
1048 in which case the previous sequence table is left untouched.