home *** CD-ROM | disk | FTP | other *** search
/ Groovy Bytes: Behind the Moon / groovybytes.iso / GROOVY / SND_TOOL / TUCPL13.ZIP / TUCGPLAY.ZIP / TUCGPLAY.DOC < prev    next >
Encoding:
Text File  |  1995-07-06  |  32.0 KB  |  758 lines
  1. TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC
  2.  
  3.                                TuCGPLAY v1.3Γ
  4.  
  5.           "It's great, it's fast, it's fantastic...it must be TuC!"
  6.  
  7.  
  8.                      - Coding & examples by FReAKeR / TuC -
  9.         Betatesting/Documentation/Anti-Social-Behaviour by SiNECuRE / TuC
  10.  
  11.  
  12.  
  13.                  Copyright (c) 1995 The Underworld Corporation
  14.                              (rip this and die)
  15.  
  16.  
  17.        TUCGPLAY IS COPYRIGHT (C)1994-1995 BY GUNTHER VOET (AKA FREAKER)
  18.  
  19.  
  20. TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC
  21.  
  22. IMPORTANT:
  23.  
  24.   You can now include our TUCGPLAY.TPH helpfile in your helpstructure
  25.   without modifying the original libs. You can add the helpfile by going
  26.   to the 'HELP' menu, then select 'FILES', select 'NEW' and browse until you
  27.   get 'TUCGPLAY.TPH'. In short: HELP|FILES|NEW|'TUCGPLAY.TPH'.
  28.  
  29.   Then use SHIFT-F1 and take the TGP option. You will get a complete help
  30.   menu to suit your needs.
  31.  
  32. TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC
  33.  
  34.  
  35.  
  36.                          TABLE OF CONTENTS
  37.  
  38.  
  39.  
  40.     0. Disclaimer                    The Usual Legal Hassles
  41.     1. Introduction                  An Explanation Of What This Is
  42. *   2. New Features / Enhancements   New Enhancements In This Release
  43. *   3. General Features              A List Of The Capabilities
  44. *   4. The Procedures                The Built-in Functions And Procedures
  45. *   5. Files In This Package         All Files That -Should- Be In This Package
  46.     6. Current Limitations           Some Limits To TuCGPLAY
  47.     7. Future Enhancements           Stuff That May Someday Work
  48.     8. Some Useful Hints             Tricks Of The Trade
  49.     9. Credits                       Giving Us Our Credits
  50.    10. Contacting TuC                Contacting The Group
  51.    11. I'm Desperate! Help!          For The Really Hopeless
  52. *  12. Message To The Users          A Word Of Appreciation To The TGP-Users
  53.    13. Greetings                     Hi's And Ho's
  54.  
  55.  
  56. (* : Mega-important chapters! Don't skip these ones!)
  57.  
  58.  
  59.  
  60.  
  61. 0. LEGAL SHIT (DISCLAIMER)
  62.  
  63.    The author will not be held responsible for any damages resulting from
  64.    the use/misuse of the TUC-GPLAY unit or any other files included in this
  65.    package. The copyrights to all files included in this package are held
  66.    by their respective authors. However the files may be used and distributed
  67.    freely, provided that no money is charged for either the software itself
  68.    or the distribution thereof. None of the files may be reproduced in
  69.    printed form without the written permission of the author(s).
  70.  
  71.    If you want to distribute this package on media not discussed in this
  72.    disclaimer, then please ask for written permission from author(s).
  73.  
  74.    All brands and product names mentioned in this document and these
  75.    executables are trademarks/registered trademarks of their respective
  76.    holders.
  77.  
  78.    In short: -If ya blow up your PC when using this thing, you're on
  79.               your own.
  80.              -If we find out that you've been making money out of
  81.               our production, without our written permission, we'll
  82.               see you in court (or in hospital).
  83.  
  84.  
  85.  
  86.  
  87. 1. WHAT THE FUCK IS IT?! WHAT CAN I DO WITH IT?! WHEN WILL WIN9X COME OUT?!
  88.  
  89.    This question is dedicated to all the morons out there (Dragon, Dark
  90.    Ripper,...you know who you are!).
  91.    TuCGPLAY is a full-blown, full-featured, state-of-the-art module-player.
  92.    It feels comfortable with: Speaker, SB, SB/Pro, GUS, GUS/MAX, Parallel DAC,
  93.    Claudia Chiffer (who wouldn't ?!). Since the player uses 386-instructions,
  94.    a 386 or above is 'highly recommended'. The player is brought to you in
  95.    the form of two TP 7.0 tpu's that can be linked into your code.
  96.  
  97.  
  98.  
  99.  
  100. 2. WHAT'S HOT IN THIS NEW RELEASE OF TuGGPLAY ?  (NEW ENHANCEMENTS/FEATURES)
  101.  
  102.   - Helpfile included.
  103.   - MANY errors in DOC file removed. (Procedures <> Functions) (sorry guys :)
  104.   - Hardware port detection for SB (pro) added !
  105.   - Automated Polling Mode ! (the polling is now done automatically, by
  106.     linking it to a seperate timer-int. So no more "pollbuffer" every
  107.     split second!! :)
  108.   - By using the Realexesize procedure, you now no longer need to manually
  109.     define the size of the exe when using overlays. This procedure calculates
  110.     the exe-size by checking the header, so DON'T FUCK-UP THE HEADER!
  111.     Since the size is calculated, this also means you can safely compress
  112.     your work using exe-packers like pklite/diet/exepack/...
  113.   - Overlay Checking: TGP now checks if the overlay is present, if not
  114.     it will exit and return an errormessage. (no more crashes! :)
  115.   - File checking: well, basically the same as overlay-checking, but now
  116.     it checks whether or not the selected MODule is present.
  117.   - Quick Setup: a deliciously looking, lightbar-operated, setup-interface
  118.     that simply stores all the requested settings for you. It doesn't
  119.     initialize the card (only the player) nor does it load the MODule, it
  120.     simply gets the configuration. (if you're really lazy, just use the
  121.     quickload procedure :)
  122.   - Debugging Mode: checks whether or not the defined settings are correct,
  123.     and displays the current status. (simply set this to true :)
  124.   - Changed the 'Port' command to 'Musport'....So now it actually works :)
  125.   - Enhanced THX & Dolby Prologic Support
  126.   - Default frequencies are now 22.5KhZ for SB and 44.8KhZ for GUS
  127.   - Detectgus: HARDWARE-detection of the Gravis Ultrasound!
  128.     Returns the base port of the GUS-card (if present ofcoz' :)
  129.   - Freq Procedure: allows you to read and set the playing frequency.
  130.   - Override Procedure: when you use this proc, the player will not perform
  131.     any error-checking. This will result in faster loading, but ofcourse
  132.     if something goes wrong, it goes wrong in an ugly way. :)
  133.   - Even more errorchecking is performed...unless you use the override
  134.     procedure.
  135.   - Readcards Procedure: this procedure fills a record with all cards
  136.     present in your system (including their settings). This makes this
  137.     procedure an ideal utility when making your own interface.
  138.   - Bestcard Procedure: this is an extention to the Readcards Procedure,
  139.     it not only detects which cards are present, but also provides info
  140.     on the best card present (if more cards are found).
  141.   - Initdrv Procedure: initializes the sound-drivers, not the card.
  142.     This is neat when using your own interface, because it allows you
  143.     to postpone the initialization of the drivers (and herby saving memory
  144.     space) until you actually start the playing. So you have more free
  145.     memory to do some other stuff in your program before starting the music.
  146.     (e.g.: playing a wave-file before starting the mod,...)
  147.   - Initcard Procedure: applies the driver-settings to the card.
  148.     Actually this is the hardware-equivalent of the Initdrv Procedure.
  149.   - Position Procedure: allows you to read and set the position in the
  150.     MODule; cool for realtime-mixing :)
  151.   - Completely rewritten basecode which causes the player to run about
  152.     40% faster (and ofcourse now it takes up even less processor-overhead).
  153.   - Rewritten some little routines in the starfield and the player.
  154.  
  155.   Note: one of the less cool features that Freaker (our 'dearest' coder :)
  156.         added is a namechange for several of the procedures...
  157.         So if you already made something with the previous version of
  158.         TGP, be sure to recheck the procedures-list.
  159.         (this also means that i have to rewrite the entire
  160.         procedures-section :( )
  161.  
  162.  
  163.  
  164. 3. GIVE ME MORE DATA! INPUT! INPUT! INPUT! (A.K.A. GENERAL FEATURES)
  165.  
  166.    -Dolby (Prologic) Surround Optimization
  167.    -THX-Surround Optimization (try this with a with a THX-system and
  168.     a GUS/MAX!). For those of you who don't know: THX is the surround
  169.     system developed by LucasFilm, and it beats the shit out of Dolby!
  170.     THX support - this means there is a short delay across each channel.
  171.    -48KhZ on GUS/MAX (44Khz-GUS/all other devices are by default set
  172.     to 22.5Khz)
  173.    -Autodetection of Hardware: if several cards are present, TuCGPLAY
  174.     will choose the best-sounding card, or (if you choose to) will use
  175.     the card specified by you.
  176.    -Built in Initialization-Interface
  177.    -Total Background-Execution (automated polling mode)
  178.    -4K-Poll-Buffer, so the player will take up a minimum of system-overhead
  179.    -Supports MOD-files of up to 8 channels
  180.    -32 bit support, even works under OS/2
  181.    -8 octaves ST3 support
  182.    -Supports all common effects (even more - decay, ...)
  183.    -Example proggies to show you the ropes
  184.    -A very detailed doc-file provided by Sinecure (just couldn't resist :)
  185.    -24 or 31 instrument support
  186.    -Possibility to change the current MODule position (FastForward - Rewind)
  187.    -Freqs are manually (re)definable
  188.  
  189.  
  190.  
  191.  
  192. 4. THE PROCEDURES
  193.  
  194.    This is pretty important so you better read this carefully
  195.    (drinking and reading don't mix).
  196.    If you don't understand this part, go back to playing Doom.
  197.  
  198. ─────────────────────────Be─prepared─for─a─long─ride!──────────────────────────
  199.  
  200.    {$M 4096,0,8192} {This directive is NECESSARY when using the player !}
  201.  
  202. 1──────────────────────────────────────────────────────────────────────────────
  203.  
  204. * PROCEDURE TGP.QUICKLOAD(afilename:string;reask:boolean);
  205.  
  206.     -This will load the MOD from disk and ask for the hardware settings.
  207.      The hardware-settings will be saved into memory, so if you start
  208.      another MOD in the same session, the setup-questions will not be
  209.      asked again unless you specify REASK as true.
  210.     -Arguments: afilename: MOD-filename and path
  211.                 reask    : true or false (determines wether or not you
  212.                            want the hardware-settings to be reset when
  213.                            starting another MOD)
  214.  
  215. 2──────────────────────────────────────────────────────────────────────────────
  216.  
  217. * PROCEDURE TGP.FASTINIT(afilename:string;aDEVICE:word;aIRQ,aDMA:BYTE;
  218.                                                       aPORT,FREQ:WORD);
  219.  
  220.     -Using this you can force the player to skip the setup-screen, and
  221.      setup everything that is necessary to play. This procedure is actually
  222.      a combination of the Initplayer, Initcard and Loadfile procedures.
  223.      This way you can create your own setup screen if desired.
  224.      To auto-detect the hardware and still skip the setup-screen you can use
  225.      the Readcards (or Detectgus) procedure listed below.
  226.     -Arguments: afilename: MOD-filename and path
  227.                 adevice  : 1=speaker,2=DAC,3=SB,4=SB-PRO,5=SB-16/AWE32,
  228.                            6=GUS/GUS-MAX,7=NO SOUND
  229.                 airq     : Defines the IRQ setting of the card (only SB)
  230.                 adma     : Defines the DMA-channel used by the card.
  231.                            On the GUS this is the digital-DMA, NoT the
  232.                            Midi-DMA. (only SB)
  233.                 aport    : I/O port used by the card (e.g. 220h)
  234.                            (if dac, port = LPTx)
  235.                 freq     : Sets the desired frequency-rate (The GUSMAX
  236.                            defaults to 48KhZ). 440=44KhZ, 220=22KhZ,...
  237.  
  238.     -Example  : TGP.fastinit('cool.mod',6,11,5,220,440);
  239.                 Loads the file 'cool.mod', and sets up the player for
  240.                 the GUS at irq11,DMA5,port$220,44KhZ.
  241.  
  242. 3──────────────────────────────────────────────────────────────────────────────
  243.  
  244. * PROCEDURE TGP.FASTUNINIT;
  245.  
  246.     -Stops the music and clears memory.
  247.     -Arguments: none
  248.  
  249. 4──────────────────────────────────────────────────────────────────────────────
  250.  
  251. * FUNCTION TGP.LOADFILE(FILENAME:STRING):INTEGER;
  252.  
  253.     -Loads a file from disk into memory and returns an errorcode,
  254.      nothing more, nothing less. Errorcodes not equal to zero indicate
  255.      an error occured during fileload.
  256.     -Arguments: filename: MOD-filename and path, unlimited length.
  257.  
  258.     -Example  : TGP.loadfile('cool.mod');
  259.                 Loads 'cool.mod' into memory.
  260.  
  261. 5──────────────────────────────────────────────────────────────────────────────
  262.  
  263. * FUNCTION TGP.LOADMEM(ADDRESS:POINTER):INTEGER;
  264.     -Sets up a MOD, already present in memory, for use with the play-procedures
  265.      and returns an errorcode; errorcodes not equal to zero indicate an error
  266.      during the fileload. This is useful if you used your own load-routine to
  267.      insert several MODs into memory.
  268.     -Arguments: address: 32bit decimal value of the MOD-position in memory.
  269.  
  270.  !! CAUTION: the MOD will be loaded twice this way, so you have to clear the
  271.     first version yourself; if you don't know how to do this, you shouldn't be
  272.     using this function.
  273.  
  274. 6──────────────────────────────────────────────────────────────────────────────
  275.  
  276. * FUNCTION TGP.LOADOVL(STARTOVL:LONGINT):INTEGER;
  277.     -Loads the MOD from the exec-overlay. (end of file)
  278.      Also returns an errorcode (if errorcode is not equal to zero an error
  279.      has occured during ovlload). Use COPY_BIN to append the modfile to EOF of
  280.      the EXECUTABLE or use "copy /b X + Y" (where X=the exec, and Y=the mod)
  281.      to apply the object to the exec.
  282.     -Arguments: startovl: Defines the 32bit starting position of the overlay.
  283.  
  284.   !! CAUTION: You must use the size of the executable file in STARTOVL, e.g.
  285.      if your exe is 6120 bytes, then you must use 6120 as number. If you use
  286.      multiple mod files, you must copy the first modfile, then look to
  287.      at the size, and make the second procedure.
  288.  
  289.   !! HINT: You can use TGP.REALEXESIZE to get the real exesize.
  290.  
  291.     -Example  : TGP.loadovl(realexesize);
  292.                 Loads the MODule located at the end of the exe.
  293.                 If you're using several overlays, don't forget to add
  294.                 the size the previous MODule(s) to the exe-size.
  295.  
  296. 7──────────────────────────────────────────────────────────────────────────────
  297.  
  298. * PROCEDURE TGP.INITPLAYER(DEVICE:BYTE;PORT:WORD;IRQ,DMA:BYTE);
  299.     -Skips the built-in setup-interface, and uses the settings provided
  300.      by the user. This is very useful when you are using your own setup-screen,
  301.      because this way you can pass on variables to the player.
  302.      This procedure only sets up the player not the card.
  303.      This does not yet reset the interrupts, so you can still use mouse, etc.
  304.      after initializing the player.
  305.     -Arguments: device: 1=speaker,2=DAC,3=SB,4=SB-PRO,5=SB-16/AWE32
  306.                         6=GUS/GUS-MAX,7=NO SOUND
  307.                 port  : Defines the I/O port of the soundcard.
  308.                         (for DAC, use the LPT port nr)
  309.                 irq   : Defines the IRQ-channel of the device. (for SB (xx))
  310.                 dma   : Defines the DMA-channel of the device. (for SB-16/AWE)
  311.  
  312.  !! NOTE: If you want to auto-detect any of the arguments, use the variables
  313.           from the TGPI-record, provided by the Readcard-procedure.
  314.           If you use GUS, the IRQ and DMA will also be ignored.
  315.  
  316. 8──────────────────────────────────────────────────────────────────────────────
  317.  
  318. * PROCEDURE TGP.INITCARD;
  319.     -Low-Level initializes the Card.
  320.  
  321. 9──────────────────────────────────────────────────────────────────────────────
  322.  
  323. * PROCEDURE TGP.POLLMUSIC;
  324.     -Polls the player, and loads a portion of the MOD into the buffer.
  325.      Normally you shouldn't need this procedure, since the player now does
  326.      its polling automatically, but if you should experience a slowdown in
  327.      the music, then you have to poll the music in your routine.
  328.     -Arguments: none
  329.  
  330. 10─────────────────────────────────────────────────────────────────────────────
  331.  
  332. * PROCEDURE TGP.POLLBUFFER;
  333.     -The same as TGP.POLLMUSIC, but instead of a 1K buffer, this procedure
  334.      has a 4K buffer. It is therefore more suitable for heavier routines
  335.      (but ofcourse the buffer also takes up a bit more memory).
  336.      I recommend that you experiment using TGP.POLLMUSIC and TGP.POLLBUFFER,
  337.      because in some cases one might perform better than the other.
  338.      The example included in this package (TEST_TGP.EXE) uses the
  339.      TGP.POLLBUFFER method.
  340.      But, as mentioned above, you probably don't need to poll the music
  341.      manually.
  342.     -Arguments: none
  343.  
  344. 11─────────────────────────────────────────────────────────────────────────────
  345.  
  346. * PROCEDURE TGP.UNLOADMUS;
  347.     -Unloads the MOD from memory, if you don't do this the memory will
  348.      not be cleared when loading another MOD. (and so you probably won't
  349.      have enough memory :). (and stacks will block)
  350.     -Arguments: none
  351.  
  352. 12─────────────────────────────────────────────────────────────────────────────
  353.  
  354. * PROCEDURE TGP.STARTMUS;
  355.     -Starts the music, interrupts are no longer disabled, so you can still
  356.      use interrups in your program.
  357.     -Arguments: none
  358.  
  359. 13─────────────────────────────────────────────────────────────────────────────
  360.  
  361. * PROCEDURE TGP.STOPMUS;
  362.     -Pauses the music, but doesn't unload it. To resume the music, use
  363.      TGP.STARTMUS again.
  364.     -Arguments: none
  365.  
  366.  !! CAUTION: Unexpected problems might occure when using this procedure with
  367.              a SB or a Parrallel DAC. (sometimes)
  368.  
  369. 14─────────────────────────────────────────────────────────────────────────────
  370.  
  371. * FUNCTION TGP.VOLUME(NEWVOL:BYTE):BYTE;
  372.     -Change/get the master volume.
  373.      Using this procedure you can create fade-in/outs, volume-slides, and
  374.      much more. The player is by default set to the maximum volume.
  375.     -Arguments: newvol: Sets the value of the master-volume; values may vary
  376.                         from 0 to 255 (but you knew that, right? :).
  377.                         If newvol='curvol', the current volume will be shown.
  378.  
  379.     -Example  : -TGP.volume(125);
  380.                  Sets the main-channels to 125.
  381.                 -TGP.volume(curvol);
  382.                  Gets the current volume.
  383.  
  384. 15─────────────────────────────────────────────────────────────────────────────
  385.  
  386. * FUNCTION TGP.POSITION(NEWPOS:WORD):WORD;
  387.     -Let's you read or set the current position in the MODule.
  388.      Using this procedure you can rewind and skip parts of the MODule.
  389.     -Arguments: newpos: Sets the position in the MODule.
  390.                         The start of the MODule is 0.
  391.  
  392.     -Example  : TGP.position(500);
  393.                 Jumps to offset 500 in the MODule.
  394.                 TGP.position(curpos);
  395.                 Returns the current position.
  396.  
  397. 16─────────────────────────────────────────────────────────────────────────────
  398.  
  399. * PROCEDURE TGP.READCARDS;
  400.     -This procedure does an auto-detect of all audio-cards present, and
  401.      stores their settings in the TGPI-info-record.
  402.     -Arguments: none
  403.  
  404. 17─────────────────────────────────────────────────────────────────────────────
  405.  
  406. *  FUNCTION TGP.BESTCARD:BYTE;
  407.     -When you call this funtion, the Readcards procedure is called, and
  408.      in addition to that the Bestcard variable (part of the TGPI-record)
  409.      if filled with the settings of the best card detected in your system.
  410.      The device number of the best card is also returned.
  411.     -Arguments: none
  412.     -Note     : The card selection is as follows:
  413.                 1.GUS/GUS-MAX   4.SB
  414.                 2.SB-16/AWE32   5.SPEAKER
  415.                 3.SB-PRO        (DAC can't be detected !)
  416.  
  417. 18─────────────────────────────────────────────────────────────────────────────
  418.  
  419. * FUNCTION TGP.REALEXESIZE:LONGINT;
  420.     -Returns the true size of the executable, ignoring compression by pklite
  421.      or other exe-packers. The exe-size is calculated by using the info
  422.      provided in the header of the exe, so don't mess with the header because
  423.      then this procedure might/will not work correctly.
  424.     -Arguments: none
  425.     -The file-size is returned in the form of a longint (but you already guessed
  426.      that, i suppose :)
  427.  
  428. 19─────────────────────────────────────────────────────────────────────────────
  429.  
  430. * FUNCTION TGP.DETECTGUS:WORD;
  431.     -A hardware detection routine for the GUS/GUS-MAX, returns the base
  432.      address (NOT in HEX)
  433.     -Arguments: none
  434.     -Note     : To convert this value to hex, use the 'word2hex' procedure
  435.                 listed below.
  436.  
  437. 20─────────────────────────────────────────────────────────────────────────────
  438.  
  439. * FUNCTION TGP.DETECTSB:WORD;
  440.     -A hardware detection routine for the SB/SBPRO, returns the base
  441.      address (NOT in HEX)
  442.     -Arguments: none
  443.     -Note     : To convert this value to hex, use the 'word2hex' procedure
  444.                 listed below.
  445.  
  446. 21─────────────────────────────────────────────────────────────────────────────
  447.  
  448. * FUNCTION TGP.WORD2HEX(BASE:WORD):WORD;
  449.     -Coverts the decimal value Base, to a Hexadecimal value; and returns
  450.      it as a word.
  451.     -Arguments: Base: the value you wish to convert (e.g.: the address returned
  452.                       by detectgus)
  453.  
  454. 22─────────────────────────────────────────────────────────────────────────────
  455.  
  456. * FUNCTION TGP.FREQ(FREQSET:WORD):WORD;
  457.     -Let's you set or read the current frequency.
  458.     -Arguments: freqset: the frequency you want to set
  459.                 curfreq: returns the current frequency
  460.  
  461.     -Example  : -TGP.freq(222);
  462.                  Sets the frequency to 22.2KhZ.
  463.                 -TGP.freq(curfreq);
  464.                  Returns the current freq-value.
  465.                  Instead of using 'curfreq' you can also use '65535'.
  466.  
  467.   !! CAUTION: this function can only be used before calling initplayer.
  468.  
  469. 23─────────────────────────────────────────────────────────────────────────────
  470.  
  471. * PROCEDURE TGP.SHOWDRV;
  472.     -Does a writeln of all the sound-cards supported by TGP.
  473.     -Arguments: none
  474.  
  475. 24─────────────────────────────────────────────────────────────────────────────
  476.  
  477. * FUNCTION TGP.INITDRV:BYTE;
  478.     -This thing initializes the internal music-drivers of the player, and
  479.      returns the number of drivers currently installed in TGP.
  480.     -This does not initialize the card! Use initcard for that.
  481.     -Arguments: none
  482.  
  483. 25─────────────────────────────────────────────────────────────────────────────
  484.  
  485. * PROCEDURE TGP.QUICKSETUP;
  486.     -Calls the built-in, lightbar-driven, setup-menu and lets you define
  487.      all settings required to run the player. The settings are stored in
  488.      the tgp.info record. (for info on this record see below)
  489.     -Arguments: none
  490.     -Note     : Feel free to use this built-in screen; it is very stable
  491.                 and it will save you hours of coding to make your own
  492.                 interface. (ofcourse, the die-hard coders will ignore my
  493.                 advice and make their own interface :)
  494.  
  495. ───────────────────────────────────────────────────────────────────────────────
  496.  
  497. *  MAIN VARIABLES AND TGP DIRECTIVES !
  498.  
  499.    DEBUGMODE : BOOLEAN;                               (* Debug mode         *)
  500.  
  501.    Give USEFUL debug info (can be used in your releases !, no annoying debug
  502.    info !)
  503.  
  504.  
  505.    FORCEALL : BOOLEAN;                                (* Force all          *)
  506.  
  507.    Force all options, NO errorchecking, so: sloppy quit, errors, crashes,...
  508.  
  509. ───────────────────────────────────────────────────────────────────────────────
  510.  
  511. * THE INFAMOUS TGP-INFORMATION RECORD.
  512.  
  513.  TYPE TGPI =
  514.        RECORD
  515.  
  516.         VOLUME : BYTE;                                 (* Current volume     *)
  517.  
  518.          DETECT :
  519.            RECORD
  520.              DEVICE : ARRAY[1..6] OF                   (* Current device det *)
  521.                       RECORD
  522.                         PRESENT: BOOLEAN;              (* Device present ?   *)
  523.                         IRQ    : BYTE;                 (* Interrupt          *)
  524.                         PORT   : WORD;                 (* Port               *)
  525.                         DMA    : BYTE;                 (* DMA channel        *)
  526.                       END;
  527.            END;
  528.  
  529.          BESTCARD :                                    (* Best card installed
  530.                                                           in the system      *)
  531.            RECORD
  532.              DEVICE : BYTE;                            (* Best devicenumber  *)
  533.              IRQ    : BYTE;                            (* irq number         *)
  534.              PORT   : WORD;                            (* port number        *)
  535.              DMA    : BYTE;                            (* DMA channel        *)
  536.            END;
  537.  
  538.            FORCED :                                    (* Forced device (you)*)
  539.            RECORD
  540.              IRQ    : BYTE;                            (* irq number         *)
  541.              PORT   : WORD;                            (* port number        *)
  542.              DMA    : BYTE;                            (* dma channel        *)
  543.              DEVICE : BYTE;                            (* device number      *)
  544.              FREQ   : WORD;                            (* Frequency          *)
  545.            END;
  546.        END;
  547.  
  548.  VAR INFO : TGPI;
  549.  
  550. You can call this record by using the redirected variable TGP.INFO
  551.  
  552.  
  553. ─────────────────────Pfew!─That─about─covers─the─Procedures──(i─hope─:)────────
  554.  
  555.  
  556.  
  557.  
  558. 5. FILES IN THIS PACKAGE
  559.  
  560.    If one or more of the following files is missing from your TGP-package,
  561.    then you've got a problem. You can always find the entire TGP-package
  562.    on ToXiC DReAMS (TuC WHQ): +32-15-31.93.76
  563.  
  564.    FILE_ID  DIZ           756 <Description of TGP for boards               >
  565.    FILES    LST         1,312 <All files included in this package          >
  566.    TGP_SUP  COM        13,213 <TGP (TuC) WHQ -> Support & Distribution site>   
  567.    COPY_BIN ZIP         7,306 <COPY binairy data on .EXE or any bin. file  >
  568.    TUC_DEMO ZIP         3,864 <Sinecure's starfield routine                >
  569.    TUCGPLAY ZIP        55,449 <TUC GPLAY main routines                     >
  570.  
  571.      * TUCGPLAY TPU        59,984  <TUCGPLAY low level routines>
  572.      * TGP      TPU        25,712  <TUCGPLAY interface unit    >
  573.      * TUCGPLAY REF        15,551  <Quick reference chart      >
  574.      * TUCGPLAY.DOC        32,751  <What are you reading ?     >
  575.      * TUCGPLAY.TPH        47,636  <Helpfile for TP/BP 7.0     >
  576.  
  577.    TGP_EXAM ZIP       513,632 <Examples for TUC gplay>
  578.  
  579.      *  EXAMPLE1 ???  <QUICKLOAD: interface, load module, play>
  580.         EXAMPLE2 ???  <Low level load a modfile and play it.  >
  581.         EXAMPLE3 ???  <QUICKSETUP: interface, load ovl, play  >
  582.         EXAMPLE4 ???  <Find bestcard, load module, play       >
  583.         EXAMPLE5 ???  <Autodetection routine example          >
  584.         EXAMPLE6 ???  <Fastload from disk by using lowlevelr. >
  585.         EXAMPLE7 ???  <Play a second modfile after the 1st one>
  586.  
  587.  
  588.  
  589.  
  590. 6. CURRENT LIMITATIONS
  591.  
  592.    -TuCGPLAY only works with modules of the MOD-format.
  593.    -The modules are limited to 64 patterns
  594.    -The sample-size is limited to 63K (but that's more a limitation to the
  595.     MOD-format, than to the player)
  596.  
  597.  
  598.  
  599.  
  600. 7. FUTURE ENHANCEMENTS
  601.  
  602.    Stuff that MiGHT be added someday:
  603.     -Support for other formats
  604.     - ? ? ?
  605.  
  606.  
  607.  
  608. 8. SOME USEFUL HINTS
  609.  
  610.    -Add the helpfile included in this package to your IDE !
  611.    -If you're having trouble creating your own setup-interface, don't feel
  612.     ashamed to use the built-in interface; after all, we made it so you
  613.     could -use- it!
  614.    -NEVER EVER EVER FORGET TO UNINITIALIZE THE PLAYER!
  615.     (unless you want your pc to crash)
  616.    -Don't forget to checkout the examples
  617.    -{$M 4096,0,8192} {This directive is NECESSARY when using the player !}
  618.    -If you intend to set the volume of the player - the default is set to
  619.     maximum volume (255) -
  620.    -Checkout the included quick-reference-card; better yet: print it and
  621.     hang it on the wall so you can read from it while coding :)
  622.    -A default program that uses the player would have the following structure:
  623.  
  624.          Program Proggy_Doe;
  625.  
  626.          {$M 4096,0,8192}                { Don't forget this one!             }
  627.  
  628.           Uses TGP;
  629.  
  630.           Begin
  631.  
  632.                tgp.quickload('TUCGPLAY.MOD',false);
  633.                                          { Quickload file tucgplay.mod        }
  634.                                          { Or, when using a custom interface, }
  635.                                          { use the seperate procedures.       }
  636.  
  637.                tgp.startmus;             { Start playing the MODule.          }
  638.  
  639.                <YOUR CODE>               { Run the stuff that makes you so    }
  640.                                          { proud. :)                          }
  641.  
  642.                tgp.fastuninit;           { Clear memory and card-settings.    }
  643.  
  644.           End.
  645.  
  646.  
  647.  
  648.  
  649. 9. CREDITS
  650.  
  651.    -If you use TuCGPLAY, please feel free to send us your work, or let us know
  652.     what you think of the player. For information on contacting TuC, see below.
  653.  
  654.    -TGP represents hundreds of hours of coding, we offer you the possibility
  655.     to use this great player at no cost, so we believe that greetings or at
  656.     least a word of thanks in your work would not be misplaced.
  657.  
  658.     Less polite: We can't force you to include us in your credits list, but
  659.                  it would be FUCKiNG LAME not to!
  660.                  And besides, we WILL eventually discover that you used our
  661.                  player without giving credit where credit's due; and then
  662.                  you can expect to be mentioned in every new TuC-release...
  663.                  in the HATES-section that is.
  664.  
  665.  
  666.  
  667. 10. CONTACTING TUC
  668.  
  669.    We can be reached at 32-15-319376 (ToXiC DReaMS / TuC WHQ).
  670.    Or by sending E-mail to:
  671.  
  672.            Freaker (Coding) :
  673.  
  674.                    Fido: 2:292/504@Fidonet.Org
  675.                Internet: Freaker@f504.n292.z2.Fidonet.Org
  676.               real name: Gunther Voet
  677.  
  678.            Sinecure (Betatesting/Dox) :
  679.  
  680.                    Fido: Sinecure@2:292/504.0@Fidonet.org
  681.                       &  2:292/805.25@Fidonet.Org
  682.                Internet: Sinecure@f504.n292.z2.Fidonet.Org
  683.                       &  Sinecure@p25.f805.n292.z2.Fidonet.Org
  684.               real name: Stefan Allaert
  685.  
  686.      Please send your comments/suggestions about the documentation to
  687.      me (Sinecure), instead of to Freaker. Our coder doesn't have the time
  688.      to answer/read all of your comments, I do :)
  689.  
  690.  
  691.  
  692.  
  693. 11. HELP! I DON'T UNDERSTAND ANYTHING OF WHAT YOU SAID!
  694.  
  695.    Make your own pick:
  696.    -Forget all about coding and run Windows.
  697.    -Commit suicide.
  698.    -Contact a real coder to explain the procedures to you.
  699.    -Try and try again....
  700.    -Just use the force. :)
  701.    -If you're REALLY REALLY REALLY desperate, write me or Freaker
  702.     a message stating your problem.
  703.  
  704.  
  705.  
  706.  
  707. 12. MESSAGE TO THOSE WHO CONTACTED US
  708.  
  709.     We would like to thank the following people for their comments/support:
  710.     (in no particular order!)
  711.  
  712.     Special Thanx: Marc Van Leeuwen (for hatching the player in PascalNet)
  713.                                     (Sorry for the angry message dude.   )
  714.                    Jonas Maebe      (For the excellent beta-report.      )
  715.                    Sven Van Soom    (No explanation needed :-)           )
  716.                    Hobbit (Onno)    (No explanation needed :-)           )
  717.  
  718.  
  719.     Normal Thanx :
  720.  
  721.         Claudio Tagliola (Holland), Marco Van Den Helm (Holland),
  722.         Jouri Geys (Belgium), Frido Otten (Holland), Mark Rogers (US),
  723.         Jan Tegtmeier (Germany), Joerg Lange (Germany), Karl Prosser (US),
  724.         Nils Deslè (Purple Zebra/Belgium).
  725.  
  726.         All users of the Fido-Pascal areas. (Hmm..well maybe not ALL users :)
  727.  
  728.         If there's someone out-there that can put TGP on an FTP-site,
  729.         please send us a message and do so! :)
  730.  
  731.  
  732.  
  733.  
  734. 13. THE GREETINGS (in no particular order !)
  735.  
  736.    -Big Thanx Go Out To: the makers of the included MODules.
  737.                          For using those MODs in our examples.
  738.                          We don't know who you are, but if you send us your
  739.                          names we can include you in the credits.
  740.  
  741.    -Group Greetings: PMA, TLi (NoT TLy), CoR, ASPHYXiA, FC, NFF, ECR, IMG
  742.  
  743.    -Personal Greetings
  744.  
  745.         Sinecure: EZ-DiCK - Corona - The Hobbit - Natural Mystic - P.M
  746.                   The Orme - Antonio Roffo.
  747.  
  748.  
  749.         Freaker : The Hitman - Spiritual Steven - Eric Cumps - Pliny
  750.                   McGarreth - Madflight -  Neon & Pulze - Tasmaniac.
  751.  
  752.  
  753.  
  754.                                                         - SiNECuRE / TuC
  755.  
  756. TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC
  757. 320704070595-13R-Γ
  758.