

		               /---/  /       /---/   \   /
		                  /---/  /       /---/     \-/
		               /      /____   /   /       /
		        

                         Useless Module Player v1.1

               	      Application Programming Interface
 
                             By FreddyV/Useless


    This file contains a full description of the API for USS.ASM, USMPLAY.ASM,
  File Loaders, TIMER.ASM, MEMORY.ASM HARDWARE.ASM and FILES.ASM


    * WATCOM C/C++ users:
    
       The interface file (usmplay.h) contains only the more important
     functions. A list of the available functions is at the end of this file.

-------------------------------------------------------------------------------

		    File Loaders API (MODLOAD.ASM, XMLOAD.ASM...)

-------------------------------------------------------------------------------


    There is only one function in each loader:

   - xxx_Load

     Description: Load a xxx file (xxx can be MOD, STM, S3M, XM ,IT or USM)

     Input: ESI Offset to the file name string.
	    EAX Default panning setting. (20202020h for Mono)
            EBX=LM_File   Load module from a file.
            EBX=LM_Memory Load module from memory.
 
     Output: CF Clear -> USM Header pointer is in ESI 
	     CF Set -> Error code in EAX


-------------------------------------------------------------------------------

			 Useless USM Play API (USMPLAY.ASM)

------------------------------------------------------------------------------- 


 Music synchro variables:
 ------------------------

	  
 - _SynchroCount  DWORD
    
    It's incremented each time a Wxx or a EFxx effect occur.


 - _SynchroVal    BYTE

   _SynchroVal is set to the Wxx or EFx effect parameter.


 - _MusicEnd      BYTE

   _MusicEnd is set to 1 when the music is finished.

   Note: the music is looped.


 - _Order         WORD (0 to Orders in the music-1)

   It contains the current position in the order table.


 - _Pattern       WORD (0 to Patterns in the music-1)

   It contains the current pattern number.


 - _Row           WORD (1 to Rows in the current pattern)

   It contains the current row number.


 - _ChInstrument  BYTE*MAX_PLCHANNELS
 
 - _ChNote        BYTE*MAX_PLCHANNELS
 
 - _ChCommand     BYTE*MAX_PLCHANNELS


 Order change functions.
 -----------------------


 - USMP_PrevOrder

   Description: Go to the previous music pattern.

     Input:  --

     Output: --

     Note:

      * It can be removed if you set Use_USMP_PrevOrder to No in SETUP.INC  
     
 
 - USMP_NextOrder

   Description: Go to the next music pattern.

     Input:  --

     Output: --

     Note:

      * It can be removed if you set Use_USMP_NextOrder to No in SETUP.INC  
      
 
 - USMP_SetOrder

   Description: Set the current order number.

     Input:  AX New Order number. (0 to Orders in music-1)

     Output: --
     
     Note:

      * It can be removed if you set Use_USMP_SetOrder to No in SETUP.INC  
 

 - USMP_SetPosition

   Description: Set the current order and row number.

     Input:  AX New Order number. (0 to Orders in music-1)
	     BX New row.          (0 to Rows in the current pattern-1)

     Output: --
     
     Note:

      * It can be removed if you set Use_USMP_SetOrder to No in SETUP.INC  
 

 Music Load/Free functions.
 --------------------------


 - USMP_LoadInternalModule

   Description: Load an "internal" USM file.

     Input: ESI Pointer to the USM file in memory.

     Output: --
     
     Note:
	 
      * The file can be included in the EXE or loaded dirrectly.

 - USMP_FreeInternalModule

   Description: Free an USM module loaded with LoadInternalModule.

     Input: ESI Pointer to an USM Header.    

     Output: CF Clear -> Ok
	     CF Set   -> Error code in EAX.
     
     Note:

      * It can be removed if you set UseFreeInternalModule to No in SETUP.INC

 - USMP_FreeModule

   Description: Free the USM module from memory.

     Input: ESI Pointer to an USM Header.    

     Output: CF Clear -> Ok
	     CF Set   -> Error code in EAX.
     
     Note:

      * You can't use this function after a call to LoadInternalModule.

      * It can be removed if you set UseFreeModule to No in SETUP.INC  
 

 Music Start/Stop functions.
 ---------------------------

 
 - USMP_StartPlay
   
   Description: Start the music replay.

     Input: ESI Pointer to an USM Header.

     Output: CF Clear -> Ok
	     CF Set   -> Error code in EAX.


 - USMP_StopPlay       
   
   Description: Stop the music replay.

     Input: --

     Output: --


-------------------------------------------------------------------------------

                       Useless Sound System API (USS.ASM)

-------------------------------------------------------------------------------

    USS.ASM does the complete samples and Instruments managing.

    This API will change in a near future, I don't guarantee for this API
    compatibility with the other player version.

    I will add a complete API for playing sound effects (not before v1.05).

	     
 Sound system Setup/Initialisation.
 ----------------------------------


 - USS_Setup

   Description: Display the setup menu and let the user to choose the sound 
		output.

     Input:  --

     Output: CF Clear -> Ok
	     CF Set -> The choosen device is incorrect or Escape key pressed.
     
     Note:

      * It can be removed if you set UseSetup to No in SETUP.INC
	(Setup code is big and Setup function need memory function)


 - USS_SetAmpli
 
   Description: Define the amplification value for the mixed devices.
   
     Input:  EAX Amplification value (0-65535)

     Output: --
     
   

 - USS_AutoSetup

   Description: It does an automatic sound device detection.

     Input: --

     Output: --
     
     Note: 
	       
      * The detected device is the best available device.
	( GUS first, then SB16 ...)

      * It can be removed if you set UseAutoSetup to No in SETUP.INC  

 - USS_Init 
 
   Description : Sound System initialisation.
   
     Input: --

     Output: -- 

     Note: This function is called by USMP_StartPlay
       
 - USS_SetActiveChannels

   Description: Set the number of active sound system channels
   
     Input: Number of channels to use.   
     
     Output: --


 Sound Stop/Start functions.
 ---------------------------


 - USS_StartOutput

   Description: Start the Sound System sound output.

     Input:  ESI Pointer to the periodic function called by the sound driver.

     Output: CF Clear -> Ok
	     CF Set -> Error code in EAX
     
     Note:
      
      * The periodic function can be called by the computer timer or a
	sound card IRQ.
	When the function is called, eax contains the number of periode 
	( one period is 1/1193180 second) elapsed since the previouscall.

       * The number of active channels MUST be set before with the 
	 USS_SetActiveChannels function.


 - USS_StopOutput

   Description: Stop the Sound System sound output.

     Input:  --

     Output: CF Clear -> Ok
	     CF Set -> Error in EAX


 - USS_UpdateOutput

 - USS_UpdateInstr


 Samples Load and Free functions.
 --------------------------------

 
 - USS_LoadSample

 - USS_FreeSample


 Global or channels sound functions.
 -----------------------------------


 - USS_GetGlobalVolume

 - USS_SetGlobalVolume

 - USS_GetChannelVolume
 
 - USS_SetChannelVolume
 
 - USS_StartInstrument
 
 - USS_InitInstrEnv

 - USS_SetEnvPos
 
 - USS_GetSampleVolume

 - USS_GetSamplePanning

 - USS_SetSampleOffset
 
 - USS_SetNote
 
 - USS_GetPeriod
 
 - USS_SetPeriod

 - USS_GetNotePeriod
 
 - USS_GetVolume
 
 - USS_SetVolume
 
 - USS_GetPanning
 
 - USS_SetPanning

 - USS_NoteCut
 
 - USS_NoteFade
 
 - USS_KeyOff

-------------------------------------------------------------------------------

                      Memory manager API (MEMORY.ASM)

-------------------------------------------------------------------------------


  - _Maxavail  
  
    Description: Return the length of the biggest available memory block.
  
    Input: --

    Output: EAX Length of the biggest available memory block.

    Note:
     
     * This function is not available if you are using WATCOM C/C++

  - _Malloc
  
    Description: Allocate a memory block.

    Input: EAX Amount of needed Memory.

    Output: CF Clear -> Memory block @ in EAX
	    CF Set -> Error code in EAX

  - _Calloc    
  
    Description: Allocate and clear a memory block.

    Input: EAX Amount of needed Memory.

    Output: CF Clear -> Memory block @ in EAX
	    CF Set -> Error code in EAX

  - _Free      Free a memory block.

    Description: Free a memory block.

    Input: EAX @ of the memory block to free.

    Output: CF Clear -> Ok
	    CF Set -> Error code in EAX

-------------------------------------------------------------------------------

                         Timer manager API (TIMER.ASM)

-------------------------------------------------------------------------------

  - Timer_Start_
		       
     Description: Start a timer.

     Input: EAX Timer Procedure Offset
	    EBX Timer Speed ( EBX/1193180 hz )
		       
     Output: CF clear -> Ok
	     CF set   -> EAX=TE_NoFreeTimer (No more timer available)

     Note:

      * You can't start more than "max_timers" timers (defined in SETUP.INC)

  - Timer_Stop_

     Description: Stop a timer.

     Input: EAX Timer Proc to stop.

     Output: CF clear -> Ok
	     CF set   -> EAX=TE_NotFound (It's not a correct proc offset)


-------------------------------------------------------------------------------

                      'Hardware' functions API (HARDWARE.ASM)

-------------------------------------------------------------------------------


    HARDWARE.ASM and HARDWARE.INC included all the IRQ/DMA functions.
    They are also used to initialise the pointers to the more usefull
  informations in memory. (PSP, Environment variables and 'Zero' Offset)


  - Public variable:

    ZeroOffset, PSPOffset and EnvOffset
    
     Note:
     
     * They are initialised by the 'HardwareInit' Function

  - HardwareInit
		       
     Description: It does all the public variable initialisation and
                  the DMA buffer allocation.

     Input: --
		       
     Output: --

     Note:

      * This MUST be the first funtion call if you use USMPLAY.

  - GetEnvOffset
  
     Description: Returns the Environement variable Offset

     Input: EAX, Offset of the variable name

     Output: EDI, Variable offset if CF cleared


     Example:
     
        BlasterEnv DB 7,'BLASTER'       ; 7 is the environment var size.

        mov eax,Offset BlasterEnv
	call GetEnvOffset
        jc Error

  - DMA_Setup
   
     Description: Program a channel on the 8237 DMA controler.
     
     Input: AL  Mode Register  ( bits 0..1 ignored )
            AH  channel   ( 0..7 )
            EBX Physical Base Address ( 0..0ffffffh )
            ECX Bytes to transfer     ( 1..10000h )

     Output: --

     Note:
     
     * This function was done by Adam Seychell (DOS32 coder)     

    - IRQ_Enable

     Description: Enable an Hardware IRQ
                                                                         
     Input: DL, IRQ Number                                                   
                                                                         
     Output: --                                                             

  - IRQ_Disable

     Description: Disable an Hardware IRQ
                                                                         
     Input: DL, IRQ Number                                                   
                                                                         
     Output: --                                                             


  Macros defined in HARDWARE.INC:


  - SetInt Macro Inter,Select,Offs

     Description: Set a new interrupt function
     
  - GetInt Macro Inter,_Ptr

     Description: Get an interrupt function pointer

  - RestInt Macro Inter,_Ptr

     Description: Restore an interrupt function 

  - SetIRQ Macro IRQ,Select,Offs

     Description: Set a new interrupt function

  - GetIRQ Macro IRQ,_Ptr

     Description: Get an interrupt function pointer

  - RestIRQ Macro IRQ,_Ptr

     Description: Restore an interrupt function 


-------------------------------------------------------------------------------

	 Available functions/variables for WATCOM C/C++ (in USMPLAY.H)

-------------------------------------------------------------------------------


 Useless USM Play Functions/Variables (USMPLAY.ASM)
 --------------------------------------------------


   Synchro variables.

 - unsigned int   SynchroCount;
 - unsigned char  SynchroVal;
 - unsigned char  MusicEnd;
 - unsigned short Order;      (0 to Orders in the music-1)
 - unsigned short Pattern;    (0 to Patterns in the music-1)
 - unsigned short Row;        (1 to Rows in the current pattern)

 - unsigned short ChInstrument[MAX_PLCHANNELS];
 - unsigned short ChNote[MAX_PLCHANNELS];
 - unsigned short ChCommand[MAX_PLCHANNELS];


   Player functions.


 - void USMP_LoadInternalModule(void *music);

 - void USMP_FreeInternalModule(void *music);


 - void USMP_FreeModule(void *music);


 - void USMP_StartPlay(void *music);

 - void USMP_StopPlay(void);


 - void USMP_PrevOrder(void);

 - void USMP_NextOrder(void);

 - void USMP_SetOrder(unsigned int order);

 - void USMP_SetPosition(unsigned int order, unsigned int row);


 Useless Sound System functions (USS.ASM)
 ----------------------------------------

 
 - void USS_Setup(void);

 - void USS_AutoSetup(void);

 - void USS_SetAmpli(int Ampli);


 Some device information.
 ------------------------

 - char *DEV_Name;                Device Name
 - unsigned short DEV_BasePort;   Device Base Port
 - unsigned char DEV_IRQ;         Device Interrupt
 - unsigned char DEV_DMA;         Device DMA


 Files loaders (STMLOAD.ASM, MODLOAD.ASM, XMLOAD.AXM ...)
 --------------------------------------------------------
 

 - void *MOD_Load(unsigned int loadmode, unsigned int panning, char *filename);

 - void *STM_Load(unsigned int loadmode, unsigned int panning, char *filename);

 - void *S3M_Load(unsigned int loadmode, unsigned int panning, char *filename);

 - void *XM_Load(unsigned int loadmode, unsigned int panning, char *filename);

 - void *IT_Load(unsigned int loadmode, unsigned int panning, char *filename);

 - void *USM_Load(unsigned int loadmode, unsigned int panning, char *filename);


 Timer functions (TIMER.ASM)
 ---------------------------


 - int Timer_Start(void *function,int speed);

 - int Timer_Stop(void *function);


 Error variable and function (ERROR.ASM)
 ---------------------------------------

 
 - int Error_Number;

   It contains the Error number. 0 for no error.


 - void Display_Error(int Error_Number);
 
   Call this to display the error name.
   

 'Hardware' Init function (HARDWARE.ASM)
 ---------------------------------------


 - void HardwareInit(unsigned long psp);
