<listitem><para><emphasis>bx_sb16_c</emphasis> is the class containing the emulator itself, thatis the part acting on port accesses by the application, handling theDMA transfers and so on. It also prepares the data for the outputclasses.</para></listitem><listitem><para><emphasis>bx_sound_output_c</emphasis> is the base output class. It has allthe methods used by the emulator, but only as stubs and does notactually produce any output. These methods are then called bythe emulator whenever output is necessary.</para></listitem><listitem><para><emphasis>bx_sound_OS_c</emphasis> is derived from <emphasis>bx_sound_output_c</emphasis>. It contains the code to generate output for the <emphasis>OS</emphasis> operating system. It is necessary to override allthe methods defined in the base class, unless virtual functionsare used. Note that this should remain an option, so try tooverride all methods, even if only as stubs. They should bedeclared <emphasis>virtual</emphasis> if and only if <emphasis>BX_USE_SOUND_VIRTUAL</emphasis>is defined, just as in the examples. The constructor should call the inherited constructoras usual, even though the current constructor does not doanything yet.</para></listitem></itemizedlist></section><section><title>Methods</title><para>The following are the methods that the output class has to override.All but constructor and destructor have to return either<emphasis>BX_SOUND_OUTPUT_OK</emphasis> <emphasis>(0)</emphasis> if the function was successful, or <emphasis>BX_SOUND_OUTPUT_ERR</emphasis> <emphasis>(1)</emphasis> if not. If any of the initializationfunctions fail, output to that device is disabled until the emulator is restarted.</para></section><section><title>bx_sound_OS_c(bx_sb16_c*sb16)</title><para>The emulator instantiates the class at the initialization of Bochs.</para><para>Description of the parameter:</para><itemizedlist><listitem><para><emphasis>sb16</emphasis> is a pointer to the emulator class. This pointer can then be used to access for example the <emphasis>writelog</emphasis> function to generatesound-related log messages. Apart from that, no access to the emulatorshould be necessary.</para></listitem><listitem><para>The constructor should <emphasis>not</emphasis> allocate the output devices. This shouldn't be done until the actual output occurs; in either <emphasis>initmidioutput()</emphasis> or <emphasis>initwaveoutput()</emphasis>.Otherwise it would be impossible to have two copies of Bochs running concurrently (if anybody ever wants to do this).</para></listitem></itemizedlist></section><section><title>~bx_sound_OS_c()</title><para>The instance is destroyed just before Bochs ends.</para></section><section><title>int openmidioutput(char *device)</title><itemizedlist><listitem><para><emphasis>openmidioutput()</emphasis> is called when the first midi output starts.It is only called if the midi output mode is 1 (midimode 1). It shouldprepare the given MIDI hardware for receiving midi commands.</para></listitem><listitem><para><emphasis>openmidioutput()</emphasis> will always be called before <emphasis>openwaveoutput()</emphasis>,and <emphasis>closemidioutput()</emphasis>will always be called before <emphasis>closewaveoutput()</emphasis>, but not in all cases will both functions be called.</para></listitem></itemizedlist></section><section><title>Description of the parameters:</title><itemizedlist><listitem><para><emphasis>device</emphasis> is a system-dependent variable.It contains the value of the <emphasis>MIDI=device</emphasis> configuration option.</para></listitem><listitem><para>Note that only one midi output device will be used at any one time.<emphasis>device</emphasis>may not have the same value throughout one session, but it will be closedbefore it is changed.</para></listitem></itemizedlist></section><section><title>int midiready()</title><para><emphasis>midiready()</emphasis> is called whenever the applications asks if themidi queue can accept more data. </para><para>Return values:</para><itemizedlist><listitem><para><emphasis>BX_SOUND_OUTPUT_OK</emphasis> if the midi output device is ready.  </para></listitem><listitem><para><emphasis>BX_SOUND_OUTPUT_ERR</emphasis> if it isn't ready.  </para></listitem></itemizedlist><para><emphasis>Note: </emphasis><emphasis>midiready()</emphasis> will be called a few times<emphasis>before</emphasis> the device is opened. If this is the case, it shouldalways report that it is ready, otherwise the application (not Bochs)will hang.</para></section><section><title>int sendmidicommand(int delta, int command, int length, Bit8u data[])</title><para><emphasis>sendmidicommand()</emphasis>is called whenever a complete midi command hasbeen written to the emulator. It should then send the given midi command to the midi hardware.It will only be called after the midi output has been opened. Note thatif at all possible it should not wait for the completion of the commandand instead indicate that the device is not ready during the executionof the command. This is to avoid delays in the program while it isgenerating midi output.</para><para>Description of the parameters:</para><itemizedlist><listitem><para><emphasis>delta</emphasis> is the number of delta ticks thathave passed since the last command has been issued. It is always zero forthe first command. There are 24 delta ticks per quarter, and 120 quartersper minute, thus 48 delta ticks per second.</para></listitem><listitem><para><emphasis>command</emphasis> is the midi command byte (sometimescalled status byte), in the usual range of 0x80..0xff. For more informationplease see the midi standard specification.</para></listitem><listitem><para><emphasis>length</emphasis> is the number of data bytes thatare contained in the data structure. This does <emphasis>not</emphasis> include the statusbyte which is not replicated in the data array. It can only be greaterthan 3 for SysEx messages (commands <emphasis>0xF0</emphasis> and <emphasis>0xF7</emphasis>)</para></listitem><listitem><para><emphasis>data[]</emphasis> is the array of these data bytes,in the order they have in the standard MIDI specification.Note, it might be <emphasis>NULL</emphasis> if length==0.</para></listitem></itemizedlist></section><section><title>int closemidioutput()</title><para><emphasis>closemidioutput()</emphasis> is called before shutting down Bochs or when theemulator gets the <emphasis>stop_output</emphasis> command through the emulator port.After this, no more output will be necessary until <emphasis>openmidioutput()</emphasis>is called again, but <emphasis>midiready()</emphasis> might still be called. It should do the following:</para><itemizedlist><listitem><para>Wait for all remaining messages to be completed</para></listitem><listitem><para>Reset and close the midi output device</para></listitem></itemizedlist></section><section><title>int openwaveoutput(char *device)</title><para><emphasis>openwaveoutput()</emphasis> is called when the first wave output occurs,and only if the selected wavemode is 1. It should do the following:</para><itemizedlist><listitem><para>Open the given device, and prepare it for wave output</para></listitem></itemizedlist><para><emphasis>or</emphasis></para><itemizedlist><listitem><para>Store the device name so that the device can be opened in <emphasis>startplayback()</emphasis>.</para></listitem></itemizedlist><para><emphasis>openmidioutput()</emphasis> will always be called before <emphasis>openwaveoutput()</emphasis>,and <emphasis>closemidioutput()</emphasis>will always be called before <emphasis>closewaveoutput()</emphasis>, but not in all cases will both functions be called.</para><para><emphasis>openwaveoutput()</emphasis> will typically be called once, whereas<emphasis>startplayback()</emphasis> is called for every new DMA transfer to the SB16 emulation. If feasible,it could be useful to open and/or lock the output device in<emphasis>startplayback()</emphasis> as opposed to <emphasis>openwaveoutput()</emphasis>to ensure that it can be used by other applications while Bochs doesn'tneed it.</para><para>However, many older applications don't use the auto-init DMAmode, which means that they start a new DMA transfer for every singleblock of output, which means usually for every 2048 bytes or so.Unfortunately there is no way of knowing whether the application willrestart an expired DMA transfer soon, so that in these cases the<emphasis>startwaveplayback</emphasis> function will be called very often, and itisn't a good idea to have it reopen the device every time.</para><para>The buffer when writing to the device should not be overly large.Usually about four buffers of 4096 bytes produce best results. Smallerbuffers could mean too much overhead, while larger buffers contributeto the fact that the actual output will always be late when the applicationtries to synchronize it with for example graphics.</para><para>The parameters are the following: </para><itemizedlist><listitem><para><emphasis>device</emphasis> is the wave device selected bythe user. It is strictly system-dependent. The value is that of the<emphasis>WAVE=device</emphasis>configuration option.</para></listitem></itemizedlist><para>Note that only one wave output device will be used at any one time.<emphasis>device</emphasis> may not have the same value throughout one session, but it will be closedbefore it is changed.</para></section><section><title>int startwaveplayback(int frequency, int bits, int stereo, int format)</title><para>This function is called whenever the application starts a new DMA transfer.  It should do the following:</para><itemizedlist><listitem><para>Open the wave output device, unless <emphasis>openwaveoutput()</emphasis> did thatalready</para></listitem><listitem><para>Prepare the device for data and set the device parameters to those givenin the function call</para></listitem></itemizedlist><para>The parameters are the following:</para><itemizedlist><listitem><para><emphasis>frequency</emphasis> is the desired frequency of theoutput. Because of the capabities of the SB16, it can have any value between5000 and 44,100.</para></listitem><listitem><para><emphasis>bits</emphasis> is either 8 or 16, denoting the resolutionof one sample.</para></listitem><listitem><para><emphasis>stereo</emphasis> is either 1 for stereo output, or 0 for mono output.</para></listitem><listitem><para><emphasis>format</emphasis> is a bit-coded value (see below).</para></listitem></itemizedlist><para><table>   <title>format bits</title><tgroup cols="2"><thead><row><entry>Bit number</entry><entry>Meaning</entry></row></thead><tbody><row> <entry> 0 (LSB)  </entry><entry><para> 0: unsigned data </para><para>                                            1: signed data </para></entry> </row><row> <entry> 1..6     </entry><entry> Type of codec (see below) </entry> </row><row> <entry> 7        </entry><entry><para> 0: no reference byte </para><para>                                             1: with reference byte </para></entry> </row><row> <entry> 8..x     </entry><entry> reserved (0) </entry> </row></tbody></tgroup></table><table>   <title>codecs</title><tgroup cols="2"><thead><row><entry>Value</entry><entry>Meaning</entry></row></thead><tbody><row> <entry> 0 </entry><entry> PCM (raw data) </entry> </row><row> <entry> 1 </entry><entry> reserved </entry> </row><row> <entry> 2 </entry><entry> 2-bit ADPCM (Creative Labs format) </entry> </row><row> <entry> 3 </entry><entry> 2.4-bit (3-bit) ADPCM (Creative Labs format) </entry> </row><row> <entry> 4 </entry><entry> 4-bit ADPCM (Creative Labs format) </entry> </row></tbody></tgroup></table></para><para>Other codecs are not supported by the SB hardware. In fact, most applications willtranslate their data into raw data, so that in most cases the codec will be zero.</para><para>The number of bytes per sample can be calculated from this as (bits / 8) * (stereo + 1).</para></section><section><title>int waveready()</title><para>This is called whenever the emulator has another output buffer readyand would like to pass it to the output class. This happens every<emphasis>BX_SOUND_OUTPUT_WAVEPACKETSIZE</emphasis> bytes, or whenever a DMA transferis done or aborted.</para><para>It should return whether the output device is ready for another bufferof <emphasis>BX_SOUND_OUTPUT_WAVEPACKETSIZE</emphasis> bytes. If <emphasis>BX_SOUND_OUTPUT_ERR</emphasis>is returned, the emulator waits about 1/(frequency * bytes per sample) seconds and then asks again. The DMA transfer is stalled during that time, butthe application keeps running, until the output device becomes ready.</para><para>As opposed to <emphasis>midiready(), waveready()</emphasis> will <emphasis>not</emphasis> becalled unless the device is open.</para></section><section><title>int sendwavepacket(int length, Bit8u data[])</title><para>This function is called whenever a data packet of at most <emphasis>BX_SB16_WAVEPACKETSIZE</emphasis>is ready at the SB16 emulator. It should then do the following:</para><itemizedlist><listitem><para>Send this wave packet to the wave hardware</para></listitem></itemizedlist><para>This function <emphasis>has</emphasis> to be synchronous, meaning that it <emphasis>has</emphasis>to return immediately, and <emphasis>not</emphasis> wait until the output is done. Also,this function might be called before the previous output is done. If yourhardware can't append the new output to the old one, you will have to implementthis yourself, or the output will be very chunky, with as much silencebetween the blocks as the blocks take to play. This is not what you want.Instead, <emphasis>waveready()</emphasis> should return <emphasis>BX_SOUND_OUTPUT_ERR</emphasis>until the device accepts another block of data.</para><para>Parameters:</para><itemizedlist><listitem><para><emphasis>length</emphasis> is the number of data bytes inthe data stream. It will never be larger than <emphasis>BX_SB16_WAVEPACKETSIZE</emphasis>.</para></listitem><listitem><para><emphasis>data</emphasis> is the array of data bytes.</para></listitem></itemizedlist><para>The order of bytes in the data stream is the same as that in the Wave file format:<table>   <title>wave output types</title><tgroup cols="2"><thead><row><entry>Output type</entry><entry>Sequence of data bytes</entry></row></thead><tbody><row> <entry> 8 bit mono </entry><entry> Sample 1; Sample 2; Sample 3; etc. </entry> </row><row> <entry> 8 bit stereo </entry><entry> Sample 1, Channel 0; Sample 1, Channel 1; Sample 2, Channel 0; Sample 2, Channel 1; etc. </entry> </row><row> <entry> 16 bit mono </entry><entry> Sample 1, LSB; Sample 1, MSB; Sample 2, LSB; Sample 2, MSB; etc. </entry> </row><row> <entry> 16 bit stereo </entry><entry> Sample 1, LSB, Channel 0; Sample 1, MSB, Channel 0; Sample 1, LSB, Channel 1; Sample 1, MSB, Channel 1; etc. </entry> </row></tbody></tgroup>