*****************************************************************************
         JiNX Sound System for Windows Interface Description 

                       revision 1 - 24/1/99
                    Saxon Druce (Penfold/JiNX)
*****************************************************************************

THIS DOCUMENT DESCRIBES THE JINX SOUND SYSTEM IN TERMS OF ITS WINDOWS PORT

JSS = JiNX Sound System
JSSwin = JiNX Sound System for Windows

The JSSwin's interface consists entirely of functions written in C. To access 
the standard interface, #include "jss_win.h" in your programme. This file
will in turn include jss_com.h (common functions), jss_comp.h (compiler
specific definitions) and itstruct.h (.IT format structures). You therefore
need to have all 4 of these header files available in order to use the 
JSSwin.

You will also need to include in your project the appropriate library based
on your choice of compiler (see the readme.txt file for more information),
as well as dsound.lib and dxguid.lib, from the DirectX SDK, version 5.0 or
newer.

See the readme.txt file for the conditions of use of the JSSwin code
library.

*****************************************************************************

The JSSwin was designed to be as similar as possible to the original JSS
for DOS as possible, however there are inevitably some differences. Instead
of making this document a description of the entire JSSwin, this document
will only describe the differences between JSSwin and the original JSS. You
should read this document in conjuction with the JSS_Interface_Rev9.txt
file, which describes the interface to the JSS for DOS, in order to gain
full information on how to use the JSSwin.

CONTENTS

1.  SetUp and Initialisation
2.  Timing and Synchronisation
3.  Alternative Means of Choosing Your Sound Card/Driver

1. Setup and Initialisation
~~~~~~~~~~~~~~~~~~~~~~~~~~~

(see JSS_Interface_Rev9.txt section 2 for reference)

-> int JiNX_SS_EnumerateSoundDevices(void);

Before doing anything with the JSSwin, you must call this function (the
original JSS has no equivalent). This function will query your available
sound hardware to find out what you have.

-> int JiNX_SS_ChooseDevice(void);

Similar to the equivalent in the original JSS, in that it offers a simple
way to select an appropriate sound device. The difference is that the
function in the original JSS has a parameter 'int autodetect', which
specifies whether the function should autodetect your sound hardware or
present a menu (of sorts) with which to select your settings.

However, since it is near impossible to show any kind of menu in a 
windows programme which is consistent across all possible types of
windows executable, this function always autodetects and so there is no
need for the parameter.

This function will select your primary sound device if you have one, or
select the 'no sound' driver if there are no Direct Sound devices
available.

See the later section 3 for more information on selecting your sound
card.

-> int JiNX_SS_PreInitSoundSystem(int zero_volume_cutoff_ticks, 
                                  int reverb_delay_in_ms, int reverb_level, 
                                  int continuous_samples);

This function has exactly the same parameters as the original JSS, with each
parameter having the same meaning. However, in the original JSS the
reverb_delay_in_ms field has a range of 50 to 300 ms, with a default of 100.
In the JSSwin, the range is 400 to 10000, with a default of 400. This is
because the JSS uses a reverb system where the reverb delay is related to
the size of the internal mixing buffers. Due to the inherent delay within
the Windows operating system between events occurring and them being
signalled, the JSSwin can not use buffers as small as the JSS for DOS, and
so the reverb delay must be larger.

-> int JiNX_SS_InitSoundSystem(HWND hWnd, int type, int freq, int num_vcs);
-> int JiNX_SS_InitSoundSystemMax(HWND hWnd, int frequency, int num_vcs);

These functions are similar to their counterparts of the same name in the
original JSS, except for the additional HWND hWnd parameter. This parameter
is a handle to the window with which the sound playback should be associated.

2. Timing and Synchronisation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(see JSS_Interface_Rev9.txt sections 7 and 10 for reference)

-> int JiNX_SS_InstallAccurateTimer(void);
-> int JiNX_SS_UninstallAccurateTimer(void);
-> float JiNX_SS_WhatTimeIsIt(void);

Use of these functions is a lot simpler in the JSSwin than in the original 
JSS, because you don't need to worry about interrupts. For this reason
the JiNX_SS_InstallAccurateTimer() function takes no parameters in the
JSSwin.

Internally these functions use QueryPerformanceFrequency and
QueryPerformanceCounter, so they are quite high resolution, and so should
suffice for all of your timing needs.

IMPORTANT: Note that if you want the no sound driver to properly update
the internal state of module playback, as well as return the correct time
with the JiNX_SS_WhatTimeIsIt() function, you *MUST* handle window messages
for the window whose handle you passed into JiNX_SS_InitSoundSystem(),
and you must allowed WM_TIMER messages to pass through, either by returning
DefWindowProc() of them or calling the callback yourself. Under the no sound
driver, the granularity with which the module playback information is
updated will depend on how often you handle your window messages. If only
win95/98 had winNT's timing functions...

3. Alternative Means of Choosing Your Sound Card/Driver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(see JSS_Interface_Rev9.txt section 9 for reference)

The following functions allow you to make your own functions for selection
of sound driver, rather than letting JiNX_SS_ChooseDevice() auto detect it.

-> int JiNX_SS_ReturnNumberOfDevices(void);

The same as the original JSS, except that unlike the original JSS, where
the returned value is fixed to the number of sound cards supported by the
JSS, the number returned by this function depends on the sound drivers
in your system reported by Direct Sound.

-> char *JiNX_SS_DeviceDescription(int device);

Also the same as the original JSS, except that it does not index into a 
fixed list - it instead indexes into what hardware is currently 
available in your system.

Device 0 will always be 'No Sound', and device 1 will probably be your
Primary Sound Driver (if you have one). After that is up to your hardware
configuration.

-> int JiNX_SS_DetectDevice(void);

Returns 1 (primary sound driver) if you have one, or 0 (no sound) otherwise.

-> int JiNX_SS_GetDevicePort(void);
-> int JiNX_SS_GetDeviceIRQ(void);
-> int JiNX_SS_GetDeviceDMA(void);
-> int JiNX_SS_GetDeviceDMAHigh(void);

None of these functions exist in the JSSwin since they aren't relevant.

-> int JiNX_SS_SetDevice(int device);

Unlike the original JSS function, this JSSwin equivalent has only the one
device parameter, since that is the only one relevant.

*****************************************************************************

The JiNX Sound System and related materials are Copyright (C) 1997-1999 Mark 
Hodson.  The Windows Port of the JiNX Sound System and related materials are
Copyright (C) 1998-1999 Saxon Druce.

DISCLAIMER:

Any demo programmes or code libraries from JiNX carry no warranty either 
expressed or implied.  The authors are not responsible for any damages caused 
by their use or misuse.  You are NOT PERMITTED to decompile, disassemble or 
in any way reverse-engineer any of the demo programmes or source libraries. 

*****************************************************************************
