Pocket-G dynamic wave mixer library

Using the library

Version 1.01

For Windows CE Version 3.0 Operating System

The information in this document is subject to change without notice and does not present a commitment on the part of TDRD Ltd.,Part. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the term of the agreement. It is against the law to copy the software on any medium except as specifically allowed in the license or nondisclosure agreement. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photo-copying and recording, for any purpose without the express written permission of TDRD.

Copyright (C) TDRD Ltd.,Part. 1997-2001. All rights reserved.

Contents

Chapter 1 - Introducing the Pocket-G dynamic wave mixer library

Chapter 2 - Building programs with Pocket-G dynamic wave mixer library

Appendix - APIs reference


CHAPTER 1

Introducing the Pocket-G dynamic wave mixer library (pgsnd.dll)

The Pocket-G dynamic wave mixer library is a real-time multi-channel audio mixer.With one music channel included. The library allows for a maximum of 32 channels to be mixed at one given time. This increases performance for both your games and multimedia applications. The library is in dynamic linking library (DLL) form. Which is easy to use for most software developer tools under Windows CE.

Features

Limitations

If you use the library, you can not use standard sound APIs, such as, sndPlaySound(…).

For first initialization, you must specify the playback quality and mix chunk size. The mixing chunk length should be as short as possible. The number will be different for each hardware device. If the number is smaller then required, you will hear choppy/ static sound while it is playing.On top of that, if it is too long re-mix delay will occur.

Ex: if it is played back at 8000 Hz and you would like to make the remix position every 1/ 10 sec you must then specify the mix chunk to 8000 / 10 = 800 bytes in length.

The wave file must be in 8 bits PCM format (not compressed).

The MOD tile must be original Amiga MOD.


CHAPTER 2

Building programs with the Pocket-G dynamic wave mixer library

Before using the library, you will need to call pg_WaveInit(…) API. It will take over the sound system of the device. Therefore, you are unable to use any standard sound API, such as sndPlaySound(…).

While you are running your application, and then you wish to switch tasks (using another application), your program will lose focus but still run. You will need to then have other applications use the wave device while our previous application is inactive because the pg_WaveInit(…) is hooked to it. Typically, when your application loses focus or becomes inactive, Windows will automatically send WM_ACTIVATE to the application Window. The wParam will indicate that your application became inactive or it will return to active status. The pg_WaveActivate(…) will correct the problem.

Ex:

WM_ACTIVATE:
    pg_WaveActivate((BOOL)wParam);
    break;

The concept of pgsnd.dll is to allocate slots/ channels of sound. When wanting to play the desired sound, just specify the slot number. The sound will then be issued to the hardware output device. To load sound to any slot, pg_WaveLoad(…) API is used to handle this task. If you load new sound to any existing slot, the previous sound will be automatically removed and replaced with the new one.

Ex:

pg_WaveLoad(g_hInst, 1000, 0); // load wave to slot 0
  .
  .
  .
  .
pg_WavePlay(0,FALSE); // start to play wave from slot 0

There are only two APIs that are used to manage the sound slots, they are,

Ex:

pg_WaveSetChannelValume(…)
pg_WaveStop(…)

For background music, you can play one song at a time. To load the music, using pg_LoadMod(…) API the song needs to be saved. To play your songs, you need to use pg_PlayMod(…) API. If you load new music, the previous one will automatically unload and it will be replaced with the new one. You can stop play by using pg_ModStop(…) API.

Volume control: there are three volume control types; main volume, music volume and last of all, each individual wave channel volume.

Finally, before exiting you application, you need to unhook the wave device before hand. If this is not done, sound will not be produced until you have reset the machine. Sometimes, your program may exit before calling pg_WaveClose (…) to unhook the device, this may occur by accident or there may be an error in your program. You need to reset your machine to once again have sound produced.

The best place to operate de-initialization is before exiting the application.

Ex:

while(GetMessage(....))
{
  TranslateMessage(&msg);
  DispatchMessage(&msg);
}

pg_WaveClose();

Appendix A:

Wave mixer APIs

BOOL pg_WaveInit(HWND hWndApp, int nPlayBackRate, int nMixChunkSize, int nMaxChannel);

Purpose:

To initilize the sound hardware. This function prepairs the sound hardware to enable the mixing functions and allocates all required memory.

Parameters:

Return:

0 if successful, otherwise Error

Example:

pg_WaveInit(hWnd,8000,1024,4);


VOID pg_WaveClose(void);

Purpose

Release the sound hardware to the Operating System. It also frees all allocated memory.

Parameters

No paramenter required

Return

Nothing


VOID pg_WaveActivate(BOOL fActive);

Purpose:

This function is used when the window’s main application receives the WM_ACTIVATE message from the system. It may happen that our application becomes non-active or returns to the active status. You have to pass the wParam as fActive parameter. The function temporarily disables (or releases) sound hardware to the system, to let the new active applicaion use the sound, when our application looses its focus. And, it re-hooks the sound hardware again when our application returns to the active state.

Parameters:

Return:

Nothing

Example:

case WM_ACTIVATE:
pg_WaveAvtive((BOOL)wParam);
break;


VOID pg_WavePlay(int nChannel, BOOL fLoop);

Purpose:

Starts playing back the loaded sound from the desired channel. The sound can play one time or automatic re-wind after having played to the end of the recorded sound.

Parameters:

Return:

Nothing


VOID pg_WaveStop(int nChannel);

Purpose:

Stops playing sound for the desired channel. The sound will immediately stop. You can also use this function to stop the loop playing sound.

Parameters:

Return:

Nothing


VOID pg_WaveSetVolume(int nVolume);

Purpose:

Set the mixer's main volume. This is a software volume control technique.

Parameters:

Return:

Nothing


VOID pg_WaveSetChannelVolume(int nChannel, int nLeftVolume, int nRightVolume);

Purpose:

Control the loudness of individual channels. This function supports stereo sound. For mono devices, nRightVolume has no effect.

Parameters:

Return:

Nothing


BOOL pg_LoadWaveResource(HMODULE hRes, int nResID, int nChannel);

Purpose:

Load sound from executable files, internal resources to a sound channel/slot.

Parameters:

Return:

0 if successful, otherwise Error

Remark:

To store sound resouces into executable files, you have to write down the resouce scripts specifying resouce types to “WAVE” and the audio file needs to be in PCM 8 Bits (*.wav) format.

Example:

(in resouce script)

/* store test.wave to resouce file, assign ID to 1 */
1 WAVE test.wav

(in applicaiton code)

/* load resouce ID 1 to sound slot 0 */
pg_LoadWaveResouce(hModuleInstance,1,0);


BOOL pg_LoadWaveFile(TCHAR *pchWaveFile, int nChannel);

Purpose:

Load sound from an external file to a sound channel/slot.

Parameters:

Return:

0 if successful, otherwise Error

Example:

/* load alarm.wave file to sound slot 1 */
pg_LoadWaveFile(TEXT(“\\windows\\alarm.wav”),1);


MOD music player APIs

BOOL pg_LoadMod(TCHAR *pchModFile);

Purpose:

Load a music file to memory.

Parameters:

Return:

0 if successful, otherwise Error

Remark:

You can load one music file at a time. If you load a new song, the previous one will be automatically removed from memory.


BOOL pg_PlayMod(void);

Purpose:

Start play of loaded music.

Parameters:

No parameter required

Return:

0 if successful, otherwise Error


BOOL pg_StopMod(void);

Purpose:

Stops/Pauses the playing music.

Parameters:

No parameter required

Return:

0 if successful, otherwise Error


Void pg_SetMusicVolume(int nVolume);

Purpose:

Control the loundness of the playing music.

Parameters:

Return:

0 if successful, otherwise Error

Remark:

The sound volume will be reset after a new song has been loaded.


Home Page http://www.pocket-g.com