InitDJSystem method

InitDJSystem method

Initialises the control: the call to this method is mandatory and must be performed before calling any other method that will use a player related functionality, possibly in the container form or dialog initialisation routine.

The purpose of this initialization method is to allocate the desired number of players (*), to synchronise the control with the container form, to set the output device (sound card) for each of the allocated players and, eventually, setting the DirectX buffer length in order to reduce the latency time: if using the Light edition of the control, the system default sound card is the unique available output device.

Use the value returned by the GetOutputDevicesCount method in order to know how many output devices are currently installed on the system and the GetOutputDeviceDesc method in order to retrieve the friendly name of every output device.

The output device for a certain player can be changed at a later time using the SetPlayerOutputDevice method.

For further details about "multi-player" management, take a look to the How to deal with multi-player features section.

For further details about output devices management, take a look to the How to work with multiple output devices and speakers section.

[Visual Basic]

control.InitDJSystem (

nTotalPlayers as short,

hWndParent as OLE_HANDLE,

nOutput0 as Integer,

nOutput1 as Integer,

nOutput2 as Integer,

nOutput3 as Integer

) as Integer

[C++]

short control.InitDJSystem (

short nTotalPlayers,

OLE_HANDLE hWndParent,

short nOutput0,

short nOutput1,

short nOutput2,

short nOutput3

);

Parameter	Description

nTotalPlayers	Number of players that must be allocated by the control: if the requested number exceed the maximum allowed by the control you purchased (*) then the number will be cut to the number of available players
hWndParent	Handle of the container (parent) window: for Visual Basic is represented by the hWnd property of the container form, while for Visual C++ is represented by the call to the container dialog box GetSafeHwnd member function: the return value of this call represents a HWND so it must be cast to OLE_HANDLE to avoid compiler errors
nOutput0	Number representing the zero-based index of the output device (sound card) that will be used for playback by player 0 (pass 0 for using the system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis. Check the How to use the control in your projects section for details about obtaining output devices. If the multimedia engine shouldn't find any enabled or valid output device, the container application would be notified through the WarnNoOutputDevice event.
nOutput1	Number representing the zero-based index of the output device (sound card) that will be used for playback by player 1 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.
nOutput2	Number representing the zero-based index of the output device (sound card) that will be used for playback by player 2 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis. This parameter is ignored when using the Light edition of the control.
nOutput3	Number representing the zero-based index of the output device (sound card) that will be used for playback by player 3 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis. This parameter is ignored when using the Light edition of the control.

Examples of use of the nOutputX parameters

We have already told that you can obtain the number of sound cards calling the GetOutputDevicesCount method and storing its return value into a numeric variable called, for example, nCount.

Example 1: nCount value is 1

Suppose that you must allocate two players (0 and 1); you have only one sound card that, for exclusion, will be the default one, so you can set the following values:

nTotalPlayers = 2 (*)

hWndParent = your form or dialog box HWND

nOutput0 = 0 (use default sound card)

nOutput1 = 0 (use default sound card)

nOutput2 = 0 (value ignored)

nOutput3 = 0 (value ignored)

Example 2: nCount value is 3

Call the GetOutputDeviceDesc method nCount times (once for every sound card) using a zero-based index in order to obtain every sound card friendly name (suppose you obtain A, B and C).

Now suppose that you must allocate four players (0, 1, 2 and 3) that will redirect their output in the following way:

- player 0 and player 1 must output to the system default sound card A.

- player 2 must output to sound card C.

- player 3 must output to sound card B.

You will have to call the InitDJSystem method with the following parameters:

nTotalPlayers = 4 (*)

hWndParent = your form or dialog box HWND

Value	Meaning

0	An error occurred, check the LastError property value in order to get the error code
Value > 0	The method completed successfully and this value represents the number of allocated players; if this value is less than the one of the nTotalPlayers parameter, check the maximum number of players supported by the control you purchased (*)

(*) A "player" can be compared to a physical "deck" on a DJ console, the place where you put the vinyl/CD to be played; the developer can create a console with many virtual decks that can play simultaneously many different songs on one or more sound cards, each deck having its own volume/tempo/pitch settings. The availability of a certain number of players (decks) will enable the container application to mix several songs on different output channels, giving for example the ability to play advertising spots while songs are being played/mixed on different output channels: this is very useful for multi-channel radio stations automation software.