CGame API

In the future this page will document the CGame/UI API functions, structures, and enums. (It may primarily focus on new things and changes compared to quake3.)

For now see code/cgame/cg_public.h, code/cgame/cg_syscalls.h, bottom of code/game/bg_public.h, and code/renderercommon/tr_types.h.

Streaming Sounds

A streaming sound API has been added (based on RTCW/ET, with a new queuing system). It is essentially the music background track code. It's good for long files that only play one at a time (music) and that only play once (cinematic dialog).

Overview:

Start a (non-loop) sound using;

// on stream 0, not attached to an entity, play sonic1, with volume 1.0
trap_S_StartStreamingSound( 0, -1, "music/sonic1.wav", 1.0f );

To make it loop or play another track after it, you must queue it as the next track. The queued track will automatically play when the initial track is finished and then repeat indefinitely.

// on stream 0, not attached to an entity, play sonic1, with volume 1.0
trap_S_StartStreamingSound( 0, -1, "music/sonic1.wav", 1.0f );
// on stream 0, set next track to sonic1, with volume 1.0
trap_S_QueueStreamingSound( 0, "music/sonic1.wav", 1.0f );

You can monitor the play count so that the queued track can be changed or cleared. This allows having a seemless playlist of music with many tracks.

// global variables
int backgroundTrack;
int backgroundPlayCount = 0;

...

// starting the music, such as in CG_StartMusic
trap_S_StartStreamingSound( 0, -1, "music/sonic1.wav", 1.0f );
trap_S_QueueStreamingSound( 0, "music/sonic2.wav", 1.0f );
backgroundTrack = 3; // next track to queue
backgroundPlayCount = 0; // start streaming sound sets the play count to 0

...

// In a function that runs each frame, such as CG_Refresh

int currentPlayCount = trap_S_GetStreamPlayCount( 0 );
if ( currentPlayCount != backgroundPlayCount ) {
    // engine changed to the queued track, set a new one
    backgroundPlayCount = currentPlayCount;
    trap_S_QueueStreamingSound( 0, va("music/sonic%d.wav", backgroundTrack), 1.0f );

    // cycle to next track.
    backgroundTrack++;

    // Q3A only has sonic1 to sonic6, so loop around.
    if ( backgroundTrack > 6 ) {
        backgroundTrack = 1;
    }
}

The queued track can be set to NULL or "" to make the streaming sound stop after the current track ends.

// on stream 0, clear the next track
trap_S_QueueStreamingSound( 0, NULL, 1.0f );

The sound can be stopped immediately.

// stop stream 0
trap_S_StopStreamingSound( 0 );

The volume be controlled by a custom cvar (monitor the modifiedCount, update as needed) or lower volume during a cut scene. It may not work well for fading out tracks though (not knowing how long track is, when it started, what point of buffer the system is at, etc).

// set volume for stream 0 to half
trap_S_SetStreamVolume( 0, 0.5f );

Porting Notes

refEntity_t shaderTime

shaderTime in refEntity_t has been changed from a float to an int. No longer convert milliseconds to seconds when sending time to engine. This was changed to allow fixing time precision loss issues at long uptimes in the engine later. For now, it's just a different way of storing / setting the time. Also see API change commits for engine and cgame.

Old method of setting it:

ref->shaderTime = cg.time / 1000.f;

New method of setting it:

ref->shaderTime = cg.time;

Ambient Light

In Quake 3, ambient light is added to every model that is drawn. In RTCW there is refEntity_t::hilightIntensity and RF_MINLIGHT. EF, ET, JK2/JA SP and MP have different ways as well. In Spearmint it's controlled using refEntity_t::ambientLight[3], RF_CONST_AMBIENT, and RF_NO_DIRECTED_LIGHT. See Research:refEntity_t Lighting Control for more details and game specific examples.

Cinematic Drawing

trap_CIN_PlayCinematic and trap_CIN_SetExtents in Spearmint expect x, y, width, and height to be in window coords (like all other draw system calls), Q3/RTCW/ET/EF (and all other id Tech 3 games?) expect virtual 640x480 coords. Changed in commit 62f36a.