home *** CD-ROM | disk | FTP | other *** search
/ PC Loisirs 18 / cd.iso / sharewar / mikm202 / docs / mloader.doc < prev    next >
Encoding:
Text File  |  1995-09-18  |  6.4 KB  |  208 lines
  1. ┌──────────────────────────────┐
  2. │MLOADER.C Module Documentation│
  3. └──────────────────────────────┘
  4.  
  5. Date last modified: April 14, 1995
  6.  
  7. If you want to use any of the routines of this module, include "mloader.h"
  8. and link MLOADER.C and LOADERS\LOADERS.LIB with your program.
  9.  
  10. MLOADER.C uses 2 routines of the MDRIVER.C module (MD_SampleLoad() & 
  11. MD_SampleUnLoad()) so if you want to use MLOADER without using MDRIVER you'll 
  12. have to define those two routines yourself. (see MIKCVT.C as an example on 
  13. how to do that).
  14.  
  15. ════════════════════════════════════════════════════════════════════════════════
  16.  
  17. General information:
  18.  
  19. When you're making a modplayer that has to support several different formats
  20. the best thing to do is to create your own internal module-format. In 
  21. MikMod's case this is the 'UNI' format. The loader module takes care of
  22. loading any of the known module formats and converting it into a UNI format.
  23.                                           
  24.             ┌───────────────┬─────────────────────────────┐
  25.             │LOADER BLACKBOX│                             │
  26.             ├───────────────┘                             │
  27.             │    ┌──────────┐                             │
  28.             │ ┌──┤mod loader├──┐                          │
  29.             │ │  └──────────┘  │                          │
  30.             │ │  ┌──────────┐  │                          │
  31.             │ ├──┤ult loader├──┤                          │
  32.             │ │  └──────────┘  │                          │
  33.             │ │  ┌──────────┐  │                          │
  34.             │ ╔══┤s3m loader├══╗ <- appropriate loader    │
  35.             │ ║  └──────────┘  ║    for this file         │
  36.             │ ║  ┌──────────┐  ║                          │
  37.             │ ║──┤uni loader├──║                          │
  38.             │ ║  └──────────┘  ║                          │
  39.             │ ║  ┌──────────┐  ║                          │
  40.             │ ║──┤mtm loader├──║                          │
  41.             │ ║  └──────────┘  ║                          │
  42.             │ ║  ┌──────────┐  ║  ┌─────────────────────┐ │
  43.  modfile >════╝──┤med loader├──╚══┤LOADER GLUE FUNCTIONS├─┼──>>─ unimod *
  44.             │ │  └──────────┘  │  └─────────────────────┘ │
  45.             │ │  ┌──────────┐  │                          │
  46.             │ ├──┤xm  loader├──┤                          │
  47.             │ │  └──────────┘  │                          │
  48.             │ │  ┌──────────┐  │                          │
  49.             │ ├──┤669 loader├──┤    - common loader       │
  50.             │ │  └──────────┘  │      routines            │
  51.             │ │  ┌──────────┐  │                          │
  52.             │ ├──┤far loader├──┤    - common loader       │
  53.             │ │  └──────────┘  │      variables           │
  54.             │ │  ┌──────────┐  │                          │
  55.             │ ├──┤dsm loader├──┤                          │
  56.             │ │  └──────────┘  │                          │
  57.             │ │  ┌──────────┐  │                          │
  58.             │ └──┤... loader├──┘                          │
  59.             │    └──────────┘                             │
  60.             │                                             │
  61.             └─────────────────────────────────────────────┘
  62.             
  63. To prevent having to link _all_ loaders to the loader module when you only 
  64. wanted to use the uni-loader, for example), the first thing the main module 
  65. has to do before using the loader module is to 'register' all loaders it 
  66. might need. This way only the registered drivers will get linked to the 
  67. executable.
  68.     
  69. ════════════════════════════════════════════════════════════════════════════════
  70.  
  71. void ML_RegisterLoader(LOADER *ldr)
  72. ===================================
  73.  
  74. Input parms:
  75.  
  76.     ldr     pointer to a LOADER structure
  77.  
  78.  
  79. Returns:
  80.  
  81.     -
  82.  
  83.  
  84. Description:
  85.  
  86. Before you can load any modules (with ML_LoadFN() or ML_LoadFP()) you first 
  87. have to register the loaders you want to use. This way only the registered 
  88. loaders are linked to the resulting program, so if you only wanted to support 
  89. a single format your program won't be so big.
  90.  
  91.  
  92. Example:
  93.  
  94.     [at the top of the program:]
  95.  
  96.     extern LOADER modload,uniload;
  97.  
  98.     [ at the start of the main program: ]
  99.  
  100.     {
  101.         ...
  102.  
  103.         ML_RegisterLoader(&modload);
  104.         ML_RegisterLoader(&uniload);
  105.  
  106.         ML_InfoLoader();
  107.         ...
  108.         ...
  109.  
  110.     }
  111.  
  112. (if you want to keep your program as small as possible, only use the .UNI 
  113. loader since it is the smallest loader available (go figure!) )
  114.  
  115. ════════════════════════════════════════════════════════════════════════════════
  116.  
  117. void ML_InfoLoader(void)
  118. ========================
  119.  
  120. Input parms:
  121.  
  122.     -
  123.  
  124.  
  125. Returns:
  126.  
  127.     -
  128.  
  129.  
  130. Description:
  131.  
  132. This function produces a list of all registered loader modules to stdout. Use 
  133. it _after_ you've registered all loaders using ML_RegisterLoader().
  134.  
  135. ════════════════════════════════════════════════════════════════════════════════
  136.  
  137. UNIMOD *ML_LoadFP(FILE *fp)
  138. ===========================
  139.  
  140. Input parms:
  141.  
  142.     fp    filepointer to a music module
  143.  
  144.  
  145. Returns:
  146.  
  147.     A pointer to a UNIMOD structure
  148.  
  149.     or
  150.  
  151.     NULL if an error occured during loading.
  152.  
  153.  
  154. Description:
  155.  
  156. With this routine you can load a music-module by it's file-pointer. If it 
  157. returns NULL, print myerr (MERROR.C) to see what went wrong. This routine 
  158. doesn't close the filepointer when it's done, but you can't rely on it still 
  159. having the same file-position. Use ML_Free() to free the UNIMOD when you're 
  160. done with it.
  161.  
  162. ════════════════════════════════════════════════════════════════════════════════
  163.  
  164. void ML_Free(UNIMOD *mf)
  165. ========================
  166.  
  167. Input parms:
  168.  
  169.     mf    pointer to a UNIMOD structure
  170.  
  171.  
  172. Returns:
  173.  
  174.     -
  175.  
  176.  
  177. Description:
  178.  
  179. Use this routine to free the module you loaded with ML_LoadFN() or 
  180. ML_LoadFP().
  181.  
  182. ════════════════════════════════════════════════════════════════════════════════
  183.  
  184. UNIMOD *ML_LoadFN(char *filename)
  185. =================================
  186.  
  187. Input parms:
  188.  
  189.     filename        The filename of the module you want to load.
  190.  
  191.  
  192. Returns:
  193.  
  194.     A pointer to a UNIMOD structure
  195.  
  196.     or
  197.  
  198.     NULL if an error occured during loading.
  199.  
  200.  
  201. Description:
  202.  
  203. With this routine you can load a music-module by it's filename. If it returns 
  204. NULL, print myerr (MERROR.C) to see what went wrong. Use ML_Free() to free 
  205. the UNIMOD when you're done with it.
  206.  
  207. ════════════════════════════════════════════════════════════════════════════════
  208.