home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 24 / CD_ASCQ_24_0995.iso / dos / prg / tucgp10b / tucgplay / tucgplay.doc < prev    next >
Text File  |  1995-05-08  |  19KB  |  434 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.0ß
  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.      STAR-ROUTINES IS COPYRIGHT (C)1995 BY STEFAN ALLAERT (AKA SINECURE)
  19.  
  20.  
  21. TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.                               TABLE OF CONTENTS
  29.  
  30.          0. Disclaimer                    The Usual Legal Hassles
  31.          1. Introduction                  An Explanation Of What This Is
  32.          2. Features                      A List Of The Capabilities
  33.          3. The Procedures                The Built-in Functions And Procedures
  34.          4. Current Limitations           Some Limits To TuCGPLAY
  35.          5. Future Enhancements           Stuff That May Someday Work
  36.          6. Some Useful Hints             Tricks Of The Trade
  37.          7. Credits                       Giving Us Our Credits
  38.          8. Contacting TuC                Contacting The Group
  39.          9. I'm Desperate                 For The Really Hopeless
  40.         10. Greetings                     Hi's And Ho's
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48. 0. LEGAL SHIT (DISCLAIMER)
  49.  
  50.    The author will not be held responsible for any damages resulting from
  51.    the use/misuse of the TUC-GPLAY unit or any other files included in this
  52.    package. The copyrights to all files included in this package are held
  53.    by their respective authors. However the files may be used and distributed
  54.    freely, provided that no money is charged for either the software itself
  55.    or the distribution thereof. None of the files may be reproduced in
  56.    printed form without the written permission of the author(s).
  57.  
  58.    If you want to distribute this package on media not discussed in this
  59.    disclaimer, then please ask for written permission from the author(s).
  60.  
  61.    All brands and product names mentioned in this document and these
  62.    executables are trademarks/registered trademarks of their respective 
  63.    holders.
  64.  
  65.    Quick reminder: if ya blow up your PC when using this thing, you're on
  66.    your own.
  67.  
  68.  
  69. 1. WHAT THE FUCK IS IT?! WHAT CAN I DO WITH IT?! WHEN WILL WIN9X COME OUT?!
  70.  
  71.    This question is dedicated to all the morons out there (Dragon, Dark
  72.    Ripper,...you know who you are!).
  73.    TuCGPLAY is a full-blown, full-featured, state-of-the-art module-player.
  74.    It feels comfortable with: Speaker, SB, SB/Pro, GUS, GUS/MAX, Parallel DAC,
  75.    Claudia Chiffer (who wouldn't ?!). Since the player uses 386-instructions,
  76.    a 386 or above is 'highly recommended'. The player is brought to you in
  77.    the form of two TP 7.0 tpu's that can be linked into your code.
  78.  
  79.  
  80.  
  81. 2. GIVE ME MORE DATA! INPUT! INPUT! INPUT! (A.K.A. FEATURES)
  82.  
  83.    -Dolby Surround Optimization
  84.    -THX-Surround Optimization (try this with a with a THX-system and
  85.     a GUS/MAX!). For those of you who don't know: THX is the surround
  86.     system developed by LucasFilm, and it beats the shit out of Dolby!
  87.     THX support - this means there is a short delay across each channel.
  88.    -48KhZ on GUS/MAX (44Khz-GUS/all other devices are by default set to20Khz)
  89.    -Autodetection of Hardware: if several cards are present, TuCGPLAY
  90.     will choose the best-sounding card, or (if you choose to) will use
  91.     the card specified by you.
  92.    -Built in Initialization-Interface
  93.    -Total Background-Execution (polling mode)
  94.    -4K-Poll-Buffer, so the player will take up a minimum of system-overhead
  95.    -Supports MOD-files of up to 8 channels
  96.    -32 bit support, even works under OS/2
  97.    -8 octaves ST3 support
  98.    -Supports all comon effects (even more - decay, ...)
  99.    -Example proggies to show you the ropes
  100.    -A very detailed doc-file provided by Sinecure :)
  101.    -24 or 31 instrument support
  102.  
  103.  
  104. 3. THE PROCEDURES
  105.  
  106.    This is pretty important so you better read this carefully
  107.    (drinking and reading don't mix).
  108.    If you don't understand this part, go back to playing Doom.
  109.  
  110. ─────────────────────────Be─prepared─for─a─long─ride!──────────────────────────
  111.  
  112.    {$M 4096,0,8192} {This directive is NECESSARY when using the player !}
  113.  
  114. ───────────────────────────────────────────────────────────────────────────────
  115.  
  116. * PROCEDURE TGP.QUICKLOAD(afilename:string;reask:boolean);
  117.     -This will load the MOD from disk and ask for the hardware settings.
  118.      The hardware-settings will be saved into memory, so if you start
  119.      another MOD in the same session, the setup-questions will not be
  120.      asked again unless you specify REASK as true.
  121.     -Arguments: afilename: MOD-filename and path
  122.                 reask    : true or false (determines wether or not you
  123.                            want the hardware-settings to be reset when
  124.                            starting another MOD)
  125.  
  126. ───────────────────────────────────────────────────────────────────────────────
  127.  
  128. * PROCEDURE TGP.FASTINIT(afilename:string;aDEVICE,aIRQ,aDMA:BYTE;aPORT,FREQ:WORD);
  129.     -Using this you can force the player to skip the setup-screen and start
  130.      playing the MOD using the settings provided by you. This way you can
  131.      create your own setup screen if desired. To auto-detect the hardware
  132.      and still skip the setup-screen you can use the TGP.SETDEVICE procedure
  133.      listed below.
  134.     -Arguments: afilename: MOD-filename and path
  135.                 adevice  : 0=no sound,1=speaker,2=DAC,3=SB(/PRO),4=GUS,
  136.                            5=AUTO
  137.                 airq     : Defines the IRQ setting of the card (only SB)
  138.                 adma     : Defines the DMA-channel used by the card.
  139.                            On the GUS this is the digital-DMA, NoT the
  140.                            Midi-DMA. (only SB)
  141.                 aport    : I/O port used by the card (e.g. 220h)
  142.                            (if dac, port = LPTx)
  143.                 freq     : Sets the desired frequency-rate (The GUSMAX
  144.                            defaults to 48KhZ). 440=44KhZ, 220=22KhZ,...
  145.  
  146. ───────────────────────────────────────────────────────────────────────────────
  147.  
  148. * PROCEDURE TGP.FASTUNINIT;
  149.     -Stops the music, clears memory and all interrupts.
  150.     -Arguments: none
  151.  
  152. ───────────────────────────────────────────────────────────────────────────────
  153.  
  154. * FUNCTION TGP.FILELOAD(FILENAME:POINTER):INTEGER;
  155.     -Loads a file from disk into memory and returns an errorcode,
  156.      nothing more, nothing less. Errorcodes not equal to zero indicate
  157.      an error occured during fileload.
  158.     -Arguments: filename: Null-Terminated MOD-name and path, unlimited length.
  159.                           Must be of the 'Far-Pointer' type.
  160.                           Terminate with #0! (else endless loop will occur)
  161.  
  162. ───────────────────────────────────────────────────────────────────────────────
  163.  
  164. * FUNCTION TGP.MEMLOAD(ADDRESS:POINTER):INTEGER;
  165.     -Sets up a MOD, already present in memory, for use with the play-procedures
  166.      and returns an errorcode; errorcode not equal to zero indicates an error
  167.      during the fileload. This is useful if you used your own load-routine to
  168.      insert several MODs into memory.
  169.     -Arguments: address: 32bit decimal value of the MOD-position in memory.
  170.  
  171.  !! CAUTION: the MOD will be loaded twice this way, so you have to clear the
  172.     first version yourself; if you don't know how to do this, you shouldn't be
  173.     using this function.
  174.  
  175. ───────────────────────────────────────────────────────────────────────────────
  176.  
  177. * FUNCTION TGP.OVLLOAD(STARTOVL:LONGINT):INTEGER;
  178.     -Loads the MOD from the exec-overlay. (end of file)
  179.      Also returns an errorcode (if errorcode is not equal to zero an error
  180.      has occured during ovlload). Use COPY_BIN to append the modfile to EOF of
  181.      the EXECUTABLE or use "copy /b X + Y" (where X=the exec, and Y=the obj)
  182.      to apply the object to the exec.
  183.     -Arguments: startovl: Defines the 32bit starting position of the overlay.
  184.  
  185.   !! CAUTION: You must use the size of the executable file in STARTOVL, e.g.
  186.      if your exe is 6120 bytes, then you must use 6120 as number. If you use
  187.      multiple mod files, you must copy the first modfile, then look to
  188.      at the size, and make the second procedure.
  189.  
  190. ───────────────────────────────────────────────────────────────────────────────
  191.  
  192. * PROCEDURE TGP.INITPLYR(DEVICE:BYTE;PORT:WORD;IRQ,DMA:BYTE);
  193.     -Skips the built-in setup-interface, and uses the settings provided
  194.      by the user. This is very useful when you are using your own setup-screen,
  195.      because this way you can pass on variables to the player.
  196.      This procedure only sets up the player not the card.
  197.      This does not yet reset the interrupts, so you can still use mouse, etc.
  198.      after initializing the player.
  199.     -Arguments: device: 0=no sound,1=speaker,2=DAC,3=SB(/PRO),4=GUS,5=AUTO
  200.                 port  : Defines the I/O port of the soundcard. 
  201.                         (for DAC, use the LPT port nr)
  202.                 irq   : Defines the IRQ-channel of the device. (for SB(/PRO))
  203.                 dma   : Defines the DMA-channel of the device. (for SB(/PRO))
  204.  
  205.  !! NOTE: If you select 0 for any or the arguments, that particular setting
  206.           will be auto-detected. If you use device 5, the arguments will be
  207.           ignored. If you use GUS, the IRQ and DMA will also be ignored.
  208.  
  209. ───────────────────────────────────────────────────────────────────────────────
  210.  
  211. * FUNCTION TGP.INITCARD(FREQ:WORD,DEVICE:BYTE;PORT:WORD;IRQ:BYTE):INTEGER;
  212.     -Low-Level initializes the Card using the settings provided by the user;
  213.      the DMA-channel is set by checking the TGP.INITPLYR settings.
  214.      The DMA and IRQ settings are only used with SB(/PRO).
  215.      This disables all interrupts, except for the timer-int so after you've
  216.      done this, there's no turning back.
  217.      Other cards (like SB) use the timer interrupt so some problems can
  218.      occure.
  219.     -Arguments: freq  : Sets the frequency-rate of the soundcard.
  220.                         Where 440=44KhZ, 220=22KhZ, 110=11KhZ,....
  221.                         default=22Khz.
  222.                 device: 0=no sound,1=speaker,2=DAC,3=SB(/PRO),4=GUS,5=AUTO
  223.                 port  : Defines the I/O port of the soundcard.
  224.                 irq   : Defines the IRQ-channel of the device.
  225.  
  226.  !! NOTE: If you select 0 for any or the arguments, that particular setting
  227.           will be auto-detected.
  228.  
  229.  !! NOTE: There are a couple of predefined variables that you can use in
  230.           combination with TGP.INITCARD and TGP.INITPLYR.
  231.  
  232.           tgp.filename  : pointer (0-terminated)
  233.           tgp.port      : word
  234.           tgp.irq       : byte
  235.           tgp.dma       : byte
  236.           tgp.device    : byte
  237.  
  238. ───────────────────────────────────────────────────────────────────────────────
  239.  
  240. * PROCEDURE TGP.POLLMUSIC;
  241.     -Polls the player, and loads a portion of the MOD into the buffer.
  242.      You must run this routine at least every 1/50 of a second, the more
  243.      you run it, the better it works. (the more the buffer will update)
  244.      If you experience a slowdown in the music, please use the POLLBUFFER
  245.      routine, because there is more than 1/50s processor activity.
  246.     -Arguments: none
  247.  
  248. ───────────────────────────────────────────────────────────────────────────────
  249.  
  250. * PROCEDURE TGP.POLLBUFFER;
  251.     -The same as TGP.POLLMUSIC, but instead of a 1K buffer, this procedure
  252.      has a 4K buffer. It is therefore more suitable for heavier routines
  253.      (but ofcourse the buffer also takes up a bit more memory).
  254.      I recommend that you experiment using TGP.POLLMUSIC and TGP.POLLBUFFER,
  255.      because in some cases one might perform better than the other.
  256.      The example included in this package (TEST_TGP.EXE) uses the
  257.      TGP.POLLBUFFER method.
  258.     -Arguments: none
  259.  
  260. ───────────────────────────────────────────────────────────────────────────────
  261.  
  262. * PROCEDURE TGP.UNLOADMUS;
  263.     -Unloads the MOD from memory, if you don't do this the memory will
  264.      not be cleared when loading another MOD. (and so you probably won't
  265.      have enough memory :). (and stacks will block)
  266.     -Arguments: none
  267.  
  268. ───────────────────────────────────────────────────────────────────────────────
  269.  
  270. * PROCEDURE TGP.STARTMUS;
  271.     -Starts the music, and disables all interrupts except for the timer-int.
  272.      Since this procedure disables most interrupts, don't use this thing
  273.      in a diagnostics program.
  274.     -Arguments: none
  275.  
  276. ───────────────────────────────────────────────────────────────────────────────
  277.  
  278. * PROCEDURE TGP.STOPMUS;
  279.     -Pauses the music and restores the interrupts, so you can quickly do some
  280.      heavy int-stuff. To resume the music, use TGP.STARTMUS.
  281.     -Arguments: none
  282.  
  283.  !! CAUTION: Unexpected problems might occure when using this procedure with
  284.              a SB or a Parrallel DAC.
  285.  
  286. ───────────────────────────────────────────────────────────────────────────────
  287.  
  288. * PROCEDURE TGP.VOLUME(NEWVOL:BYTE);
  289.     -Changes the master volume.
  290.      Using this procedure you can create fade-in/outs, volume-slides, and
  291.      much more.
  292.     -Arguments: newvol: Sets the value of the master-volume; values may vary
  293.                         from 0 to 255 (but you knew that, right? :).
  294.  
  295. ───────────────────────────────────────────────────────────────────────────────
  296.  
  297. * THE INFORMATION RECORD: PLEASE SO NOT MODIFY THE VARIABLES IN THIS RECORD !
  298.                           (READ ONLY !)
  299.  
  300.                TYPE TGPI = RECORD
  301.                        VOLUME : BYTE;        (* VOLUME INDICATOR *)
  302.          
  303.                     DETECT : RECORD
  304.                        DEVICE : ARRAY[1..4] OF RECORD (* 1:SPK, 2:DAC, ... *)
  305.                       PRESENT : BOOLEAN;              (* DEVICE PRESENT ? *)
  306.                           IRQ : BYTE;
  307.                          PORT : WORD;
  308.                           DMA : BYTE;
  309.                        DEVICE : BYTE;                 (* FOR EXTRA :) *)
  310.                              END;
  311.                         END;
  312.  
  313.                     FORCED : RECORD
  314.                           IRQ : BYTE;
  315.                          PORT : WORD;
  316.                           DMA : BYTE;
  317.                        DEVICE : BYTE;
  318.                          FREQ : WORD;
  319.                             END;
  320.                         END;
  321.  
  322.      VAR  INFO : TGPI;
  323.  
  324. You can call this record by using the redirected variable TGP.INFO
  325.  
  326. ─────────────────────Pfew!─That─about─covers─the─Procedures────────────────────
  327.  
  328.  
  329.  
  330. 4. CURRENT LIMITATIONS
  331.  
  332.    -TuCGPLAY only works with modules of the MOD-format.
  333.    -The modules are limited to 64 patterns
  334.    -The sample-size is limited to 63K
  335.  
  336.  
  337.  
  338. 5. FUTURE ENHANCEMENTS
  339.  
  340.    Stuff that MiGHT be added someday:
  341.     -Support for other formats
  342.     -AWE32-support (GUS RuLEZ! GUS RuLEZ!)
  343.  
  344.  
  345.  
  346. 6. SOME USEFUL HINTS
  347.  
  348.    Well, what can I say....Just take a look at the included example
  349.    (TEST_GPL.PAS), and study the procedures carefully.
  350.  
  351.    One more thing though: NEVER, EVER, EVER FORGET TO UNINITIALIZE THE PLAYER!
  352.    ('coz your PC will probably crash if you don't :)
  353.  
  354.    {$M 4096,0,8192} {This directive is NECESSARY when using the player !}
  355.  
  356.  
  357. 7. CREDITS
  358.  
  359.    -If you use TuCGPLAY, please feel free to send us your work, or let us know
  360.     what you think of the player. For information on contacting TuC, see below.
  361.    -Well, we can't force you to include us in your credit's list, but hey,
  362.     it would be FUCKiNG LAME not to!
  363.  
  364.  
  365.  
  366. 8. CONTACTING TUC
  367.  
  368.    We can be reached at 32-15-319376 (ToXiC DReaMS / TuC WHQ).
  369.    Or by sending E-mail to:
  370.  
  371.            Freaker (Coding) :
  372.  
  373.                    Fido: 2:292/504@Fidonet.Org
  374.                Internet: Freaker@f504.n292.z2.Fidonet.Org
  375.               real name: Gunther Voet
  376.  
  377.            Sinecure (Betatesting/Dox) :
  378.  
  379.                    Fido: 2:292/805.25@Fidonet.Org
  380.                Internet: Sinecure@p25.f805.n292.z2.Fidonet.Org
  381.               real name: Stefan Allaert
  382.  
  383.  
  384.  
  385. 9. HELP! I DON'T UNDERSTAND ANYTHING OF WHAT YOU SAID!
  386.  
  387.    Make your own pick:
  388.    -Forget all about coding and run Windows.
  389.    -Commit suicide.
  390.    -Change your name to Dark Raver.
  391.    -Join TrT-2001.
  392.    -Apply for a coder-position at CMP.
  393.    -Do the same at Spiral Emotions.
  394.    -Contact a real coder to explain the procedures to you.
  395.  
  396.  
  397.  
  398. 10. THE GREETINGS (in no particular order !)
  399.  
  400.    -Big Thanx Go Out To: the makers of the DUNEINTRO-MOD and the
  401.                          FLOWER-POWER-MOD. For using those MODs in our
  402.                          examples.
  403.                          We don't know who you are, so if you send us your
  404.                          names we can include you in the credits.
  405.  
  406.    -Group Greetings: PMA, TLi (NoT TLy), CoR, ASPHYXiA, FC, NFF, ECR, IMG
  407.  
  408.    -Personal Greetings 
  409.  
  410.         Sinecure: EZ-DiCK           (you'll have your GUS back soon :)
  411.                   Corona            (A coder does it with a routine :)
  412.                   The Hobbit        (Destroyed your monitor yet?    :)
  413.                   T.DV              (Found a decent handle yet?     :)
  414.                   P.M               (For being there i suppose.     :)
  415.                   The Orme          (CoJ still looks good           :)
  416.                   Antonio Roffo     (Found a Producer yet?          :)
  417.  
  418.         Freaker : The Hitman        (What is the taste of opium?          :)
  419.                   Spiritual Steven  (Prying the coffee-pot of the table?  :)
  420.                   Eric Cumps        (Call me if you are home! (doomwad)   :)
  421.                   Pliny             (Still hacking AT&T ? (MCI is better) :)
  422.                   McGarreth         (GUS sounds good (YaKnoWhatIMean)     :)
  423.                   Madflight         (Keep the board running!              :)
  424.                   Neon & Pulze      (Am I still Top-U/L'er                :)
  425.                   Tasmaniac         (Still alive?                         :)
  426.  
  427.    -Hates:
  428.                   Dark Raver        (Still the fuckhead in +32 !!)
  429.  
  430.  
  431.                                                         - SiNECuRE / TuC
  432.  
  433. TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC∞TuC
  434. 321004050895-10B-A