home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 25 / CD_ASCQ_25_1095.iso / dos / prg / dwstk200 / dws.pas < prev    next >
Pascal/Delphi Source File  |  1995-08-01  |  13KB  |  439 lines
  1. (******************************************************************************
  2. File:          dws.pas
  3. Version:     2.00
  4. Tab stops: every 2 columns
  5. Project:     The Sound ToolKit
  6. Copyright: 1994-1995 DiamondWare, Ltd.    All rights reserved.
  7. Written:     Keith Weiner
  8. Purpose:     Creates dws.tpu
  9. History:     94/10/09 KW Started
  10.                      94/11/27 EL Finalized for 1.0
  11.                      95/03/19 EL Finalized for 1.01, Added new const dws_Busy
  12.                      95/04/06 EL Finalized for 1.02, Added new const dws_IRQDISABLED
  13.                      95/04/06 EL Finalized for 1.03, (no changes)
  14.                      95/07/23 EL Finalized for 1.04, (no changes)
  15.                      95/07/23 EL Finalized for 2.00, (no changes)
  16.  
  17. NB: The dwt (timer) code is not compatible with source profilers
  18. ******************************************************************************)
  19.  
  20.  
  21.  
  22. unit DWS;
  23.  
  24. interface
  25.  
  26.  
  27.  
  28. const
  29.  
  30. (*****************************************************************************)
  31.     (*
  32.      . The following is the complete list of possible values for dws_errno.
  33.      . dws_errno may be set by any dws_ function.  Check its value whenever
  34.      . the return value of a dws_ function is 0 (error).
  35.     *)
  36.     dws_EZERO                                                  =    0;
  37.  
  38.     (* The following 3 errors may be triggered by any dws_ function *)
  39.     dws_NOTINITTED                                         =    1;
  40.     dws_ALREADYINITTED                                 =    2;
  41.     dws_NOTSUPPORTED                                     =    3;
  42.  
  43.     (* The following 4 errors may be triggered by dws_DetectHardWare *)
  44.     dws_DetectHardware_UNSTABLESYSTEM  =    4;
  45.     dws_DetectHardware_BADBASEPORT         =    5;
  46.     dws_DetectHardware_BADDMA                  =    6;
  47.     dws_DetectHardware_BADIRQ                  =    7;
  48.  
  49.     (* The following error may be triggered by dws_Kill *)
  50.     dws_Kill_CANTUNHOOKISR                         =    8;
  51.  
  52.     (* The following error may be triggered by any dws_X (mixer) function *)
  53.     dws_X_BADINPUT                                         =    9;
  54.  
  55.     (* The following 3 errors may be triggered by any dws_D (dig) function *)
  56.     dws_D_NOTADWD                                          =    10;
  57.     dws_D_NOTSUPPORTEDVER                          =    11;
  58.     dws_D_INTERNALERROR                              =    12;
  59.  
  60.     (* The following error may be triggered by dws_DPlay *)
  61.     dws_DPlay_NOSPACEFORSOUND                  =    13;
  62.  
  63.     (* The following 2 errors may be triggered by dws_DSetRate *)
  64.     dws_DSetRate_FREQTOLOW                         =    14;
  65.     dws_DSetRate_FREQTOHIGH                      =    15;
  66.  
  67.     (* The following 3 errors may be triggered by dws_MPlay *)
  68.     dws_MPlay_NOTADWM                                  =    16;
  69.     dws_MPlay_NOTSUPPORTEDVER                  =    17;
  70.     dws_MPlay_INTERNALERROR                      =    18;
  71.  
  72.     (*
  73.      . The following error may be triggered by any dws_ function
  74.      . (except dws_ErrNo and dws_Init) if called from an Interrupt
  75.      . Service Routine (ISR).  If you're not sure whether this applies
  76.      . to you: it probably doesn't.
  77.     *)
  78.     dws_BUSY                                                     =    19;
  79.  
  80.     (*
  81.      . The following error may be triggered by dws_Init, dws_Kill,
  82.      . and dws_DetectHardware.    It will only occur if interrupts are
  83.      . disabled.    Interrupts must be enabled when calling.    If you're
  84.      . not sure whether this applies to you: it probably doesn't.
  85.     *)
  86.     dws_IRQDISABLED                                      =    20;
  87.  
  88.  
  89.  
  90. (*---------------------------------------------------------------------------*)
  91.  
  92.  
  93.     (*
  94.      . The follwing section defines bitfields which are used by various
  95.      . dws_ functions.    Each bit in a bitfield, by definition, may be
  96.      . set/reset independantly of all other bits.
  97.     *)
  98.  
  99.     (* The following 2 consts indicate the capabilities of the user's hardware *)
  100.     dws_capability_FM                                  = $0001;
  101.     dws_capability_DIG                                 = $0002;
  102.  
  103.  
  104.     (* The following 2 consts indicate the status of specified digital sounds *)
  105.     dws_DSOUNDSTATUSPLAYING                      = $0001;
  106.     dws_DSOUNDSTATUSSEQUENCED                  = $0002;
  107.  
  108.  
  109.     (* The following 2 consts indicate the status of music playback *)
  110.     dws_MSONGSTATUSPLAYING                         = $0001;
  111.     dws_MSONGSTATUSPAUSED                          = $0002;
  112.  
  113.     (*
  114.      . Below are the timer rates supported by DWT.    Anything in between
  115.      . the listed values will cause the DOS/BIOS clock to tick erratically
  116.      . and is thus not allowed.  Any value higher than 145.6 Hz means
  117.      . you have some very special circumstances; DWT won't fit your needs
  118.      . anyway.
  119.     *)
  120.     dwt_18_2HZ                                                 = 0;                      (*18.2 Hz*)
  121.     dwt_36_4HZ                                                 = 1;                      (*36.4 Hz*)
  122.     dwt_72_8HZ                                                 = 2;                      (*72.8 Hz*)
  123.     dwt_145_6HZ                                              = 3;                      (*145.6 Hz*)
  124. (*****************************************************************************)
  125.  
  126.  
  127.  
  128. type
  129.  
  130.     (*
  131.      . The following section declares the record types used by the STK.  In each
  132.      . case, the user must create an instance of the record prior to making
  133.      . a call to an STK function which takes a pointer to it.  The STK does
  134.      . not keep a pointer to any of these records internally; after the call
  135.      . returns, you may deallocate it, if you wish.
  136.      .
  137.      . NB: The STK _does_ keep pointers to songs and digitized sound buffers!
  138.     *)
  139.  
  140.  
  141.     (*
  142.      . dws_DetectHardWare can be told _not_ to autodetect particular values
  143.      . about the installed hardware.    This is useful if detecting DMA channel,
  144.      . for example, consistently causes a machine lockup.  To override the
  145.      . autodetect for a setting, set the corresponding field in this struct
  146.      . to the correct value.    Otherwise, set the field to ffff hex.  Since
  147.      . the autodetect is reliable, this is the recommended course of action,
  148.      . except in cases of known problems.
  149.     *)
  150.     dws_DETECTOVERRIDES = record
  151.         baseport : word;                                    (*base addr of sound card (often 220) hex*)
  152.  
  153.         digdma     : word;                                    (*DMA channel*)
  154.         digirq     : word;                                    (*IRQ level*)
  155.  
  156.         reserved : array[1..10] of word;
  157.  
  158.     end;
  159.  
  160.  
  161.     (*
  162.      . A pointer to this record is passed to dws_DetectHardWare, which fills
  163.      . it in.  It is then passed unmodified to dws_Init.    If you plan on
  164.      . writing this record out to a file, it's important that you write
  165.      . the entire contents.  There is information (for internal STK use only)
  166.      . in the reserved[] field!
  167.     *)
  168.     dws_DETECTRESULTS = record
  169.         baseport     : word;                                (*base addr of sound card (often 220) hex*)
  170.  
  171.         capability : word;                                (*see constants, above*)
  172.  
  173.         (* The following 3 fields are only valid if FM music is supported *)
  174.         mustyp         : word;                                (*0=none, 1=OPL2*)
  175.         musnchan     : word;                                (*1=mono*)
  176.         musnvoice  : word;                                (*num hardware voices (11 for FM)*)
  177.  
  178.         (* The following 4 fields are only valid if digitized sound is supported *)
  179.         dignbits     : word;                                (*0=none, 8=8 bit*)
  180.         dignchan     : word;                                (*1=mono*)
  181.         digdma         : word;                                (*DMA channel*)
  182.         digirq         : word;                                (*IRQ level*)
  183.  
  184.         mixtyp         : word;                                (*1=software, 2+ is hardware*)
  185.  
  186.         reserved     : array[1..44] of byte;(*there are important values in here...*)
  187.  
  188.     end;
  189.  
  190.  
  191.     (*
  192.      . A pointer to this struct is passed as a parameter to dws_Init.  This
  193.      . allows the user to tell the STK to use less than the full capabilities
  194.      . of the installed sound hardware, and/or the user's sound board
  195.      . may not support every feature of the STK.
  196.     *)
  197.     dws_IDEAL = record
  198.         musictyp     : word;                 (*0=No Music, 1=OPL2*)
  199.  
  200.         digtyp         : word;                 (*0=No Dig, 8=8bit*)
  201.         digrate      : word;                 (*sampling rate, in Hz*)
  202.         dignvoices : word;                 (*number of voices (up to 16)*)
  203.         dignchan     : word;                 (*1=mono*)
  204.  
  205.         reserved     : array[1..6] of byte;
  206.  
  207.     end;
  208.  
  209.  
  210.     (*
  211.      . A pointer to this record is passed to dws_DPlay.
  212.      . Note that the soundnum field is filled in by dws_DPlay as a return value.
  213.     *)
  214.     dws_DPLAYREC = record
  215.         snd          : ^byte;                  (*pointer to buffer which holds a .DWD file*)
  216.         count      : word;                     (*number of times to play, or 0=infinite loop*)
  217.         priority : word;                     (*higher numbers mean higher priority*)
  218.         presnd     : word;                     (*soundnum to sequence sound _after_*)
  219.         soundnum : word;                     (*dws_DPlay returns a snd number from 10-65535*)
  220.  
  221.         reserved : array[1..20] of byte;
  222.  
  223.     end;
  224.  
  225.  
  226.     (* A pointer to this record is passed to dws_MPlay. *)
  227.     dws_MPLAYREC = record
  228.         track : ^byte;                         (*pointer to buffer which holds a .DWM file*)
  229.         count : word;                          (*number of times to play, or 0=infinite loop*)
  230.  
  231.         reserved : array[1..10] of byte;
  232.  
  233.     end;
  234. (*****************************************************************************)
  235.  
  236.  
  237.     dws_DOPTR  = ^dws_DETECTOVERRIDES;
  238.     dws_DRPTR  = ^dws_DETECTRESULTS;
  239.     dws_IDPTR  = ^dws_IDEAL;
  240.     dws_DPPTR  = ^dws_DPLAYREC;
  241.     dws_MPPTR  = ^dws_MPLAYREC;
  242.  
  243.     dws_WDPTR  = ^word;
  244.     dws_BTPTR  = ^byte;
  245.  
  246.  
  247. (*****************************************************************************)
  248.  
  249.  
  250. (*
  251.  . This function is callable at any time.  It returns the number of the
  252.  . last error which occured.
  253. *)
  254. function dws_ErrNo : word;
  255. (*---------------------------------------------------------------------------*)
  256.  
  257.  
  258. (*
  259.  . This procedure is called at the end of the timer ISR (interrupt service
  260.  . routine).    If you're using the optional DWT (DW Timer), this happens
  261.  . automagically.  If you wrote your own timer handler routine, you must
  262.  . call this function regularly.
  263. *)
  264. procedure dws_Update;
  265. (*---------------------------------------------------------------------------*)
  266.  
  267.  
  268. (*
  269.  . Each function in this section has a boolean return value.    A 0 (false)
  270.  . indicates that the function failed in some way.    In this case, call
  271.  . dws_ErrNo to get the specific error.  Otherwise, a return value of 1
  272.  . (true) indicates that all is well.
  273. *)
  274. function dws_DetectHardWare(dov : dws_DOPTR; dr : dws_DRPTR) : word;
  275.  
  276. function dws_Init(dr : dws_DRPTR; ideal : dws_IDPTR) : word;
  277.  
  278. (*
  279.  . If the program has called dws_Init, it _MUST_ call dws_Kill before it
  280.  . terminates.
  281.  .
  282.  . NB: Trap critical errors.    Don't let DOS put up the
  283.  .         "Abort, Retry, Fail?" text.    ('sides, it'll destroy your pretty gfx)
  284. *)
  285. function dws_Kill : word;
  286.  
  287.  
  288. (*
  289.  . The following 3 functions comprise the mixer section of the STK.  A
  290.  . value of 0 turns a channel off; a value of 255 is the loudest.
  291. *)
  292. function dws_XMaster(volume : word) : word;
  293.  
  294. function dws_XMusic(volume : word) : word;
  295.  
  296. function dws_XDig(volume : word) : word;
  297.  
  298.  
  299.  
  300. (*
  301.  . The following 10 functions comprise the digitized sound functions of
  302.  . the STK.  See the documentation for complete details.
  303. *)
  304. function dws_DPlay(dplay : dws_DPPTR) : word;
  305.  
  306. function dws_DSoundStatus(soundnum : word; result : dws_WDPTR) : word;
  307.  
  308. function dws_DSetRate(frequency : word) : word;
  309.  
  310. function dws_DGetRate(result : dws_WDPTR) : word;
  311.  
  312. (* This function is callable at any time*)
  313. function dws_DGetRateFromDWD(snd : dws_BTPTR; result : dws_WDPTR) : word;
  314.  
  315. function dws_DDiscard(soundnum : word) : word;
  316.  
  317. function dws_DDiscardAO(snd : dws_BTPTR) : word;
  318.  
  319. function dws_DClear : word;                     (*All*)
  320.  
  321. function dws_DPause : word;                     (*All*)
  322.  
  323. function dws_DUnPause : word;                 (*All*)
  324.  
  325.  
  326. (*
  327.  . The following 5 functions comprise the music functions of the STK.
  328.  . See the documentation for complete details.
  329. *)
  330. function dws_MPlay(mplay : dws_MPPTR) : word;
  331.  
  332. function dws_MSongStatus(status : dws_WDPTR) : word;
  333.  
  334. function dws_MClear : word;
  335.  
  336. function dws_MPause : word;
  337.  
  338. function dws_MUnPause : word;
  339. (*---------------------------------------------------------------------------*)
  340.  
  341.  
  342. (*
  343.  . The following 5 functions/procedures comprise the timer functions of the STK.
  344.  . See the documentation for complete details.
  345. *)
  346.  
  347. (* See const declarations above for rates*)
  348. procedure dwt_Init(rate : word);
  349.  
  350. (*
  351.  . If the program has called dwt_Init, it _MUST_ call dwt_Kill before it
  352.  . terminates.
  353.  .
  354.  . NB: Trap critical errors.    Don't let DOS put up the
  355.  .         "Abort, Retry, Fail?" text.    ('sides, it'll destroy your pretty gfx)
  356. *)
  357. procedure dwt_Kill;
  358.  
  359. (* The following 2 procedures affect the timer, but not the music *)
  360. procedure dwt_UnPause;
  361.  
  362. procedure dwt_Pause;
  363.  
  364. (*
  365.  .Number of ticks since Beginning of World
  366. *)
  367. function dwt_MasterTick : longint;
  368. (*****************************************************************************)
  369.  
  370.  
  371.  
  372. implementation
  373.  
  374.  
  375. function dws_ErrNo : word; external;
  376.  
  377. procedure dws_Update; external;
  378.  
  379.  
  380. function dws_DetectHardWare(dov : dws_DOPTR; dr : dws_DRPTR) : word; external;
  381.  
  382. function dws_Init(dr : dws_DRPTR; ideal : dws_IDPTR) : word; external;
  383.  
  384. function dws_Kill : word; external;
  385.  
  386.  
  387. function dws_XMaster(volume : word) : word; external;
  388.  
  389. function dws_XMusic(volume : word) : word; external;
  390.  
  391. function dws_XDig(volume : word) : word; external;
  392.  
  393.  
  394. function dws_DPlay(dplay : dws_DPPTR) : word; external;
  395.  
  396. function dws_DSoundStatus(soundnum : word; result : dws_WDPTR) : word; external;
  397.  
  398. function dws_DSetRate(frequency : word) : word; external;
  399.  
  400. function dws_DGetRate(result : dws_WDPTR) : word; external;
  401.  
  402. function dws_DGetRateFromDWD(snd : dws_BTPTR; result : dws_WDPTR) : word; external;
  403.  
  404. function dws_DDiscard(soundnum : word) : word; external;
  405.  
  406. function dws_DDiscardAO(snd : dws_BTPTR) : word; external;
  407.  
  408. function dws_DClear : word; external;
  409.  
  410. function dws_DPause : word; external;
  411.  
  412. function dws_DUnPause : word; external;
  413.  
  414.  
  415. function dws_MSongStatus(status : dws_WDPTR) : word; external;
  416.  
  417. function dws_MPlay(mplay : dws_MPPTR) : word; external;
  418.  
  419. function dws_MClear : word; external;
  420.  
  421. function dws_MPause : word; external;
  422.  
  423. function dws_MUnPause     : word; external;
  424.  
  425.  
  426. procedure dwt_Init(rate : word); external;
  427.  
  428. procedure dwt_Kill; external;
  429.  
  430. procedure dwt_Pause; external;
  431.  
  432. procedure dwt_UnPause; external;
  433.  
  434. function dwt_MasterTick : longint; external;
  435.  
  436.  
  437.  
  438. end.
  439.