Autodocs/xmodule.doc

   1 TABLE OF CONTENTS
   2
   3 xmodule/--background--
   4 xmodule/xmActivateSong
   5 xmodule/xmAddHook
   6 xmodule/xmAddInstrumentA
   7 xmodule/xmAddPatternA
   8 xmodule/xmAddSongA
   9 xmodule/xmCreateSong
  10 xmodule/xmDeleteSong
  11 xmodule/xmDisplayMessage
  12 xmodule/xmDisplayProgress
  13 xmodule/xmIdentifyModule
  14 xmodule/xmLoadModuleA
  15 xmodule/xmLockActiveSong
  16 xmodule/xmProcessSongA
  17 xmodule/xmRemHook
  18 xmodule/xmRemInstrument
  19 xmodule/xmRemPattern
  20 xmodule/xmRemSong
  21 xmodule/xmSaveModuleA
  22 xmodule/xmSetInstrumentA
  23 xmodule/xmSetPatternA
  24 xmodule/xmSetSongLen
  25 \fxmodule/--background--                                 xmodule/--background--
  26
  27     INTRODUCTION
  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.
  32
  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
  36         code).
  37
  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
  41         time).
  42
  43     PUBLIC SONGS
  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.
  55
  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.
  59
  60
  61     HOOKS
  62         Actually, most modular programs call them `modules', but it would
  63         have created a lot of confusion with a program like XModule :-).
  64
  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
  69         by the library.
  70
  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.
  74
  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.
  82
  83     SEE ALSO
  84         songclass/--background--, exec/ObtainSemaphore()
  85
  86 \fxmodule/xmActivateSong                                 xmodule/xmActivateSong
  87
  88     NAME
  89         xmActivateSong -- Makes a song the active one
  90
  91     SYNOPSIS
  92         success = xmActivateSong(songInfo);
  93         D0                       A0
  94
  95         ULONG xmActivateSong(struct SongInfo *);
  96
  97     FUNCTION
  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.
 101
 102     INPUTS
 103         songInfo - song to be activated. If NULL, this function will
 104             take no action.
 105
 106     RESULT
 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.
 110
 111     NOTE
 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.
 116
 117     SEE ALSO
 118
 119 \fxmodule/xmAddHook                                           xmodule/xmAddHook
 120
 121     NAME
 122         xmAddHookA -- Creates a new XModule Hook
 123         xmAddHook -- Varargs stub for xmAddHookA
 124
 125     SYNOPSIS
 126         hook = xmAddHookA(tagList)
 127         D0                A0
 128
 129         struct XMHook *xmAddHookA(struct TagItem *);
 130
 131
 132         hook = xmAddHook(Tag1,...)
 133
 134         struct XMHook *xmAddHook(ULONG,...);
 135
 136     FUNCTION
 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
 139         list.
 140
 141     INPUTS
 142         tagList - pointer to a tag list specifying how to initialize the
 143             XMHook structure.
 144
 145     TAGS
 146         XMHOOK_Type - (ULONG) Defines the pourpose of this hook. Possible
 147             values are currently NT_XMLOADER and NT_XMSAVER. (This
 148             tag is REQUIRED).
 149
 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).
 155
 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).
 161
 162         XMHOOK_Descr - (STRPTR) Verbose description of the hook
 163             (without newlines). (Defaults to NULL).
 164
 165         XMHOOK_Author - (STRPTR) Author's name.  Please, just put
 166             your full name here; no greetings, copyright notices,
 167             etc. (Defaults to NULL).
 168
 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).
 173
 174         XMHOOK_Flags - (ULONG) Sets miscellaneous flags for this hook.
 175             See xmodule.h for possible flags.
 176
 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.
 184             (Defaults to NULL).
 185
 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).
 189
 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:
 194
 195                 void RemoveHookFunc (struct XMHook *hook);
 196                                      A0
 197
 198         XMHOOK_LoadModFunc - (APTR) Pointer to the hook function which
 199             loads a module. The template for the function is:
 200
 201                 LONG LoadModFunc (BPTR fileHandle, struct SongInfo *song,
 202                                   D0               A0
 203                     struct XMHook *loader);
 204                     A1
 205
 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).
 216
 217         XMHOOK_SaveModFunc - (APTR) Pointer to the hook function which
 218             saves a module. The template for the function is:
 219
 220                 LONG SaveModFunc (BPTR fileHandle, struct SongInfo *song,
 221                                   D0               A0
 222                     struct XMHook *saver);
 223                     A1
 224
 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).
 235
 236
 237         XMHOOK_IdentifyModFunc - (APTR) Pointer to the hook function
 238             which identifies a module format. The template for the
 239             function is:
 240
 241                 struct XMHook *IdentifyModFunc (BPTR fileHandle,
 242                                                 D0
 243                     struct XMHook *hook,struct TagItem *tagList);
 244                     A0                  A1
 245
 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
 252             hooks).
 253
 254     RESULT
 255         hook - Pointer to the newly allocated XMHook structure, or
 256             NULL for failure.
 257
 258     SEE ALSO
 259         xmRemHook(), xmIdentifyModule(), xmLoadSong(), xmSaveSong()
 260
 261 \fxmodule/xmAddInstrumentA                             xmodule/xmAddInstrumentA
 262
 263     NAME
 264         xmAddInstrumentA -- Adds a instrument to a song
 265         xmAddInstrument -- Varargs stub for xmAddInstrumentA
 266
 267     SYNOPSIS
 268         instrument = xmAddInstrumentA(si, instrNum, tagList)
 269         D0                            A0  D0        A1
 270
 271         struct Instrument *xmAddInstrumentA(struct SongInfo *,LONG,
 272             struct TagItem *);
 273
 274
 275         instrument = xmAddInstrument(si,instrNum,tag1,...)
 276
 277         struct Instrument *xmAddInstrument(struct SongInfo *,LONG,LONG,...);
 278
 279     FUNCTION
 280         Adds an instrument to a song by calling the SNGM_ADDINSTRUMENT method
 281 .
 282
 283     INPUTS
 284         si - pointer to the song to which the instrument should be added.
 285         tagList - optional TagList.  See SNGM_ADDINSTRUMENT for possible tags
 286 .
 287
 288     RESULT
 289         Pointer to the new instrument or NULL for failure.
 290
 291     NOTE
 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
 294         public songs.
 295
 296     SEE ALSO
 297         xmRemInstrument(), songclass/SNGM_REMINSTRUMENT
 298
 299 \fxmodule/xmAddPatternA                                   xmodule/xmAddPatternA
 300
 301     NAME
 302         xmAddPatternA -- Adds a pattern to a song
 303         xmAddPattern -- Varargs stub for xmAddPatternA
 304
 305     SYNOPSIS
 306         pattern = xmAddPatternA(si, tagList)
 307         D0                      A0  A1
 308
 309         struct Pattern *xmAddPatternA(struct SongInfo *,struct TagItem *);
 310
 311
 312         pattern = xmAddPattern (si,tag1,...)
 313
 314         struct Pattern *xmAddPattern(struct SongInfo *,LONG Tag1,...);
 315
 316     FUNCTION
 317         Adds a pattern to a song by calling the SNGM_ADDPATTERN method.
 318
 319     INPUTS
 320         si - pointer to the song to which the pattern should be added.
 321         tagList - optional TagList.  See SNGM_ADDPATTERN for possible tags.
 322
 323     RESULT
 324         Pointer to the new pattern or NULL for failure.
 325
 326     NOTE
 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
 329         public songs.
 330
 331     SEE ALSO
 332         xmRemPattern(), songclass/SNGM_ADDPATTERN
 333
 334 \fxmodule/xmAddSongA                                         xmodule/xmAddSongA
 335
 336     NAME
 337         xmAddSongA -- Add a song to the song list
 338         xmAddSong -- Varargs stub for xmAddSongA
 339
 340     SYNOPSIS
 341         success = xmAddSongA(songInfo,position,tagList);
 342         D0                   A0       A1       A2
 343
 344         ULONG xmAddSongA(struct SongInfo *,struct SongInfo *,
 345             struct TagItem *);
 346
 347
 348         success = xmAddSong(songInfo,position,tag1,...);
 349
 350         ULONG xmAddSong(struct SongInfo *,struct SongInfo *,
 351             LONG,...);
 352
 353     FUNCTION
 354         Adds a song to the public song list. Trying to add a song
 355         twice is harmless.
 356
 357     INPUTS
 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.
 364
 365     TAGS
 366         XMSNG_Active - (BOOL) Makes this song the active one. The
 367             default is to just add the song without activating it.
 368
 369     RESULT
 370         success - Will be 0 for failure, in which case the song will
 371             not be added to the songs list. Currently, xmAddSongA()
 372             will never fail.
 373
 374     NOTE
 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
 378         conditions!
 379
 380     SEE ALSO
 381         xmRemSong()
 382
 383 \fxmodule/xmCreateSong                                     xmodule/xmCreateSong
 384
 385     NAME
 386         xmCreateSongA -- Create and initialize a new SongInfo structure
 387         xmCreateSong -- Varargs stub for xmCreateSongA
 388
 389     SYNOPSIS
 390         songInfo = xmCreateSongA(tagList);
 391         D0                      A0
 392
 393         struct SongInfo *xmCreateSongA(struct TagItem *);
 394
 395
 396         songInfo = xmCreateSong(Tag1,...);
 397
 398         struct SongInfo *xmCreateSong(ULONG,...);
 399
 400     FUNCTION
 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().
 404
 405     INPUTS
 406         tagList - pointer to an optional tag list specifying how to
 407             initialize the SongInfo structure.
 408
 409     TAGS
 410         SNGA_DefaultTracks - Sets the default number of pattern tracks for
 411             the song. Defaults to 4.
 412
 413         SNGA_DefaultPattLen - Sets the default number of pattern lines for
 414             the song. Defaults to 64.
 415
 416         SNGA_ReadyToUse - Adds one pattern and one position to the song.
 417             Defaults to FALSE.
 418
 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).
 429
 430         XMSNG_Active - (BOOL) Makes this song the active one. This tag is
 431             considered only if the XMSNG_AddToList tag is also passed.
 432
 433     RESULT
 434         songInfo - pointer to the newly allocated SongInfo structure, or
 435             NULL for failure.
 436
 437     SEE ALSO
 438         xmDeleteSong(), xmAddSongA()
 439
 440 \fxmodule/xmDeleteSong                                     xmodule/xmDeleteSong
 441
 442     NAME
 443         xmDeleteSong -- Deletes a song
 444
 445     SYNOPSIS
 446         xmDeleteSong(songInfo)
 447                      A0
 448
 449         void xmDeleteSong(struct SongInfo *);
 450
 451     FUNCTION
 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.
 455
 456     INPUTS
 457         songInfo - pointer to the SongInfo structure to be deleted.
 458             Passing a NULL pointer is harmless.
 459
 460     NOTE
 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.
 467
 468     SEE ALSO
 469         xmCreateSong(), xmRemSong()
 470
 471 \fxmodule/xmDisplayMessage                             xmodule/xmDisplayMessage
 472
 473     NAME
 474         xmDisplayMessageA -- Displays a message to the user
 475         xmDisplayMessage -- Varargs stub for xmDisplayMessageA()
 476
 477     SYNOPSIS
 478         xmDisplayMessageA(level, message, args)
 479                           DO     A0       A1
 480
 481         void xmDisplayMessageA(ULONG,APTR,LONG *);
 482
 483
 484         xmDisplayMessage(level, message, ...)
 485
 486         void xmDisplayMessage(ULONG,APTR,...);
 487
 488     FUNCTION
 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
 491         being output.
 492
 493     INPUTS
 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)
 496 ,
 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
 500 .
 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
 507             the error code.
 508         message - pointer to a string or catalog message number,
 509             when the XMDMF_USECATALOG flag is set.
 510         args - arguments for formatting.
 511
 512     EXAMPLES
 513         xmDisplayMessage (XMDMF_ALERT,
 514             "The application `%s' fucked up Windoze95 because %s.",
 515             "(unknown name)", "an error occurred");
 516
 517         xmDisplayMessage (XMDMF_USE_CATALOG | XMDMF_COMMENT,
 518             MSG_LIFE_UNIVERSE_AND_ALLTHAT, 42, "Fortytwo", "For tea too");
 519
 520         xmDisplayMessageA (XMDMF_ACTION | XMDMF_USECATALOG,
 521             MSG_READING_COMICS, NULL);
 522
 523         xmDisplayMessage (XMDMF_DOSFAULT | XMDMF_USECATALOG,
 524             MSG_CANT_LOAD_MODULE, ModuleName);
 525
 526     SEE ALSO
 527         xmDisplayProgress()
 528
 529 \fxmodule/xmDisplayProgress                           xmodule/xmDisplayProgress
 530
 531     NAME
 532         xmDisplayProgress -- Uptdates the progress bar indicator
 533
 534     SYNOPSIS
 535         abort = xmDisplayProgress(done, total)
 536                                   D0    D1
 537
 538         LONG xmDisplayMessageA(ULONG,ULONG);
 539
 540     FUNCTION
 541         Updates the position of the fuel gauge in the progress window to
 542         show the progress of an operation.  Additionally, it checks for
 543         user abort.
 544
 545     INPUTS
 546         done - a number which indicates how much of the work has
 547             been already completed
 548         total - Total number of operations to do.
 549
 550     RESULT
 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.
 553
 554 \fxmodule/xmIdentifyModule                             xmodule/xmIdentifyModule
 555
 556     NAME
 557         xmIdentifyModule -- Returns the type of a module
 558
 559     SYNOPSIS
 560         loader = xmIdentifyModule(fh, tagList)
 561         D0                        D0  A0
 562
 563         struct XMHook *xmIdentifyModule(BPTR,struct TagItem *);
 564
 565     FUNCTION
 566         Finds out a loader which is able to read the given module.
 567
 568     INPUTS
 569         fh - AmigaDOS FileHandle to examine.
 570         tagList - Additional parameters. Leave it NULL for now.
 571
 572     RESULT
 573         loader - Pointer to the first loader which knows how to load this
 574             module, or NULL otherwise.
 575
 576     NOTE
 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.
 580
 581     SEE ALSO
 582
 583 \fxmodule/xmLoadModuleA                                   xmodule/xmLoadModuleA
 584
 585     NAME
 586         xmLoadModuleA -- Loads a module and converts it in XModule format
 587         xmLoadModule -- Varargs stub for xmLoadModuleA
 588
 589     SYNOPSIS
 590         songInfo = xmLoadModuleA(fileName,tagList)
 591         D0                       A0       A1
 592
 593         struct SongInfo *xmLoadModuleA(STRPTR,struct TagItem *);
 594
 595
 596         songInfo = xmLoadModule(fileName,tag,...)
 597
 598         struct SongInfo *xmLoadModule(STRPTR,LONG,...);
 599
 600     FUNCTION
 601         Loads fileName using the correct module loader.
 602
 603     INPUTS
 604         fileName - File to read. Can be NULL if the XMSNG_FileHandle
 605             tag is passed.
 606         tagList - Additional parameters (see below).  Can be NULL.
 607
 608     TAGS
 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.
 613
 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).
 624
 625         XMSNG_Loader - (struct XMHook *) Disables automatic format
 626             checking and forces loading the module with the given
 627             loader. (Defaults to NULL).
 628
 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.
 640             (Defaults to NULL).
 641
 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
 647             inside the module.
 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.
 653             (Defaults to NULL).
 654
 655         XMSNG_Active - (BOOL) Makes this song the active one. This tag is
 656             considered only if the XMSNG_AddToList tag is also passed.
 657
 658     RESULT
 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.
 663
 664     EXAMPLE
 665         /* Load a song and add it to the SongList */
 666         si = xmLoadSongTags (file, NULL,
 667             XMSNG_AddToList, (struct SongInfo *)~0,
 668             TAG_DONE);
 669
 670         /* Check for errors even if si is not NULL */
 671         error = IoErr();
 672
 673         /* Release Semaphore got by xmLoadSong() */
 674         if (si) ReleaseSemaphore (&si->Lock);
 675
 676     SEE ALSO
 677         xmAddSongA(), xmIdentifyModule()
 678
 679 \fxmodule/xmLockActiveSong                             xmodule/xmLockActiveSong
 680
 681     NAME
 682         xmLockActiveSong -- Obtains an lock on the active song
 683
 684     SYNOPSIS
 685         song = xmLockActiveSong(mode);
 686         D0                        D0:16
 687
 688         struct SongInfo *xmActivateSong(UWORD);
 689
 690     FUNCTION
 691         Obtains an exclusive or shared lock on the active song,
 692         waiting if needed.  This call is a shortcut to:
 693
 694             ObtainSemaphoreShared (&XModuleBase->xm_BaseLock);
 695             ObtainSemaphore[Shared] (&XModuleBase->xm_CurrentSong.Lock);
 696             ReleaseSemaphore (&XModuleBase->xm_BaseLock);
 697
 698         To unlock a song obtained in this way, you just need to
 699         ReleaseSemaphore() it.
 700
 701         You MUST always lock a song before you even think to
 702         read from -or write to- its data!
 703
 704     INPUTS
 705         mode - one of SM_SHARED or SM_EXCLUSIVE.
 706
 707     RESULT
 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
 711             is active.
 712
 713     NOTE
 714         Please be careful if you call this function while holding
 715         locks on other songs.  Doing so, you run the risk of causing
 716         deadlock condition.
 717         This function does only lock the song; it is NOT guaranteed
 718         that it will remain the active one.
 719
 720     SEE ALSO
 721
 722 \fxmodule/xmProcessSongA                                 xmodule/xmProcessSongA
 723
 724     NAME
 725         xmProcessSongA -- Performs complex processing on a song
 726         xmProcessSong -- Varargs stub for xmProcessSongA()
 727
 728     SYNOPSIS
 729         result = xmProcessSongA(si, reserved, tagList)
 730                                 A0  A1,       A2
 731
 732         LONG xmProcessSongA(struct SongInfo *,void *,struct TagItem *);
 733
 734
 735         result = xmProcessSong(si, reserved, tag1, ...)
 736
 737         LONG xmProcessSongA(struct SongInfo *,void *,LONG,...);
 738
 739     FUNCTION
 740         Performs complex processing operations on a song.
 741
 742     INPUTS
 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.
 746
 747     RESULT
 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.
 751
 752     TAGS
 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
 757                 - XMOF_CUT_PATTERNS
 758                 - XMOF_REM_UNUSED_INSTRS
 759                 - XMOF_CUT_INSTR_LOOPS
 760                 - XMOF_CUT_INSTR_TAILS
 761                 - XMOF_DEFAULT
 762             XMOF_DEFAULT will select all the optimizations choosen by
 763             the user in addition to the ones specified with the other flags.
 764
 765         XMSNG_RemapInstruments - (BOOL) Performs instruments remapping.
 766
 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.
 772
 773         XMSNG_Join - (struct SongInfo *) - Joins the song with another one.
 774
 775         XMSNG_Merge - (struct SongInfo *) - Merges the song with another one.
 776
 777     NOTE
 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
 780         public songs.
 781
 782 \fxmodule/xmRemHook                                           xmodule/xmRemHook
 783
 784     NAME
 785         xmRemHook -- Removes an XModule Hook
 786
 787     SYNOPSIS
 788         xmRemHookA(xmHook)
 789                    A0
 790
 791         void xmRemHook(struct XMHook *);
 792
 793     FUNCTION
 794         Removes an XModule Hook, calls its RemoveHookFunc() and then
 795         frees its memory.
 796
 797     INPUTS
 798         xmHook - pointer to the hook to be removed.
 799
 800     SEE ALSO
 801         xmAddHook()
 802
 803 \fxmodule/xmRemInstrument                               xmodule/xmRemInstrument
 804
 805     NAME
 806         xmRemInstrument -- Removes an instrument from a song
 807
 808     SYNOPSIS
 809         xmRemInstrument(si, instrNum)
 810                         A0  D0
 811
 812         void xmRemInstrument(struct SongInfo *,LONG);
 813
 814     FUNCTION
 815         Removes an instrument from a song by calling the SNGM_REMINSTRUMENT
 816         method.
 817
 818     INPUTS
 819         si - pointer to the song to which the instrument should be removed.
 820         mum - Number of the instrument to be removed.
 821
 822     NOTE
 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
 825         public songs.
 826
 827     SEE ALSO
 828         xmAddInstrumentA(), songclass/SNGM_REMINSTRUMENT
 829
 830 \fxmodule/xmRemPattern                                     xmodule/xmRemPattern
 831
 832     NAME
 833         xmRemPattern -- Removes a pattern from a song
 834
 835     SYNOPSIS
 836         xmRemPattern(si, pattNum, replaceWith)
 837                      A0  D0,      D1
 838
 839         void xmRemPattern(struct SongInfo *,LONG,LONG);
 840
 841     FUNCTION
 842         Removes a pattern from a song by calling the SNGM_REMPATTERN method.
 843
 844     INPUTS
 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
 848             deleted pattern.
 849
 850     NOTE
 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
 853         public songs.
 854
 855     SEE ALSO
 856         xmAddPatternA(), songclass/SNGM_REMPATTERN
 857
 858 \fxmodule/xmRemSong                                           xmodule/xmRemSong
 859
 860     NAME
 861         xmRemSong -- Remove a song from the song list
 862
 863     SYNOPSIS
 864         success = xmRemSong(songInfo);
 865         D0                  A0
 866
 867         ULONG xmRemSong(struct SongInfo *);
 868
 869     FUNCTION
 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.
 874
 875     INPUTS
 876         songInfo - song to be removed. If NULL, this function will take
 877             no action.
 878
 879     RESULT
 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.
 883
 884     NOTE
 885         In order to remove a song, you must first obtain an exclusive
 886         lock on it.
 887
 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!
 891
 892     SEE ALSO
 893         xmAddSongA()
 894
 895 \fxmodule/xmSaveModuleA                                   xmodule/xmSaveModuleA
 896
 897     NAME
 898         xmSaveModuleA -- Saves a module to the specified file format
 899         xmSaveModule -- Varargs stub for xmSaveModuleA
 900
 901     SYNOPSIS
 902         error = xmSaveModuleA(songInfo, fileName, saver, tagList)
 903         D0                    A0        A1        A2     A3
 904
 905         LONG xmSaveModuleA(struct SongInfo *,STRPTR,struct XMHook *,
 906             struct TagItem *);
 907
 908
 909         error = xmSaveModule(songInfo, fileName, saver, tag1,...)
 910
 911         LONG xmSaveModule(struct SongInfo *,STRPTR,struct XMHook *,
 912             LONG,...);
 913
 914     FUNCTION
 915         Saves songInfo to fileName using the specified saver.
 916
 917     INPUTS
 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
 921             the default saver.
 922
 923     TAGS
 924         No tags are defined for this call.
 925
 926     RESULT
 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.
 934
 935     SEE ALSO
 936
 937 \fxmodule/xmSetInstrumentA                             xmodule/xmSetInstrumentA
 938
 939     NAME
 940         xmSetInstrumentA -- Sets an instrument's attributes
 941         xmSetInstrument -- Varargs stub for xmSetInstrumentA
 942
 943     SYNOPSIS
 944         success = xmSetInstrumentA(si, instrNum, tagList)
 945         D0                         A0  D0        A1
 946
 947         ULONG xmSetInstrumentA(struct SongInfo *,LONG,
 948             struct TagItem *);
 949
 950
 951         success = xmSetInstrument(si,instrNum,tag1,...)
 952
 953         ULONG xmSetInstrument(struct SongInfo *,LONG,LONG,...);
 954
 955     FUNCTION
 956         Sets an instrument's attributes by calling the SNGM_SETINSTRUMENT
 957         method.
 958
 959     INPUTS
 960         si - pointer to the song which contains the instrument to be set.
 961         tagList - instrument attributes to set.  See SNGM_SETINSTRUMENT
 962             for possible tags.
 963
 964     RESULT
 965         non zero for success.
 966
 967     NOTE
 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.
 971
 972     SEE ALSO
 973         xmAddInstrument(), songclass/SNGM_SETINSTRUMENT
 974
 975 \fxmodule/xmSetPatternA                                   xmodule/xmSetPatternA
 976
 977     NAME
 978         xmSetPatternA -- Sets pattern attributes
 979         xmSetPattern -- Varargs stub for xmSetPatternA
 980
 981     SYNOPSIS
 982         success = xmSetPatternA(si, pattNum, tagList)
 983         D0                      A0  D0       A1
 984
 985         ULONG xmSetPatternA(struct SongInfo *,ULONG,struct TagItem *);
 986
 987
 988         success = xmSetPattern (si,pattNum,tag1,...)
 989
 990         ULONG xmSetPattern(struct SongInfo *,ULONG,LONG Tag1,...);
 991
 992     FUNCTION
 993         Sets attributes of a pattern by calling the SNGM_SETPATTERN method.
 994
 995     INPUTS
 996         si - pointer to the song which contains the pattern to be set.
 997         tagList - list of attributes to set.  See SNGM_SETPATTERN for
 998             possible tags.
 999
1000     RESULT
1001         Non zero for success
1002
1003     NOTE
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.
1007
1008     SEE ALSO
1009         xmAddPattern(), songclass/SNGM_SETPATTERN
1010
1011 \fxmodule/xmSetSongLen                                     xmodule/xmSetSongLen
1012
1013     NAME
1014         xmSetSongLen -- Set the number of song positions
1015
1016     SYNOPSIS
1017         sequence = xmSetSongLen(songInfo, length)
1018         D0                      A0        D0:16
1019
1020         UWORD *xmSetSongLen(struct SongInfo *, UWORD);
1021
1022     FUNCTION
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
1030         NULL.
1031
1032     INPUTS
1033         songInfo - pointer to a SongInfo structure.
1034         length - new length of song sequence table.
1035
1036     NOTE
1037         This function will also adjust the CurrentPos field if it is found
1038         beyond the song end
1039
1040     BUGS
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.
1045
1046    RESULT
1047         Pointer to the newly allocated sequence table or NULL for failure,
1048         in which case the previous sequence table is left untouched.
1049
1050 \f