SpiEnableSync

The SpiEnableSync function establishes a synchronization group by linking a master stream to one or more slave streams. This ensures that the playback or recording of multiple media types (e.g., audio and video) remains aligned in real time.

Syntax

SpiEnableSync(hstreamMaster, paslaveList, ulNumSlaves, mmtimeSync);

Parameters

hstreamMaster (HSTREAM) - input: The handle of the stream designated as the master. This stream drives the synchronization pulses for the entire group.
paslaveList (PSLAVE) - input: A pointer to an array of SLAVE structures. Each structure identifies a slave stream handle and an `mmtimeStart` value, which defines the time offset relative to the master.
ulNumSlaves (ULONG) - input: The number of slave entries in the paslaveList array.
mmtimeSync (MMTIME) - input: The interval (in 1/3000th of a second) at which sync pulses are generated. If set to `0` or `NULL`, the system uses the default sync granularity defined in the master stream's SPCB.

Return Value

rc (ULONG) - returns

Return codes indicating success or the type of failure:

NO_ERROR: Success.
ERROR_INVALID_STREAM: Invalid master or slave stream handle.
ERROR_INVALID_NUMSLAVES: Number of slaves is zero or out of range.
ERROR_INVALID_MMTIME: The specified sync interval is not supported by the master handler.
ERROR_MASTER_USED: The master stream is already acting as a master for another group.
ERROR_STREAM_USED: One of the streams is already a member of a different sync group.
FAILURE: Stream handler-specific error.

Remarks

Synchronization is maintained automatically by the Sync/Stream Manager and the respective stream handlers.

**Mechanism**: The master stream generates periodic synchronization pulses. The Sync/Stream Manager passes these pulses to slave streams, which then adjust their clocks or processing rates to match the master's progress.
**Offsets**: The `mmtimeStart` field in the SLAVE structure allows for staggered starts. For example, if a slave stream has an `mmtimeStart` of 3000 (1 second), it will effectively wait for the master to reach the 1-second mark before it starts processing in alignment.
**Constraints**: A synchronization group can only have **one** master stream. To change the master or add/remove members from an existing group, you must first call SpiDisableSync.

Example Code

The following code establishes a synchronization group with one master (audio) and one slave (video).

#include <os2.h>
#include <os2me.h>

ULONG   ulRC;          /* Error return code      */
HSTREAM hStreamAudio;  /* Audio (Master) handle  */
HSTREAM hStreamVideo;  /* Video (Slave) handle   */
SLAVE   slave[1];      /* Sync slave array       */

/* ... Streams are created via SpiCreateStream ... */

/* Define the slave stream characteristics */
slave[0].hstreamSlave = hStreamVideo;
slave[0].mmtimeStart  = 0;  /* Start simultaneously with master */

/* Enable synchronization */
ulRC = SpiEnableSync(hStreamAudio, /* Master handle           */
                     &slave[0],    /* Pointer to slave array  */
                     1,            /* One slave stream        */
                     0);           /* Use default granularity */

if (ulRC) {
    return (ulRC); /* Error handling */
}

Related Functions

Related Messages

SHC_ENABLE_SYNC