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:

There can be up to 24 streams (numbered 0 to 23). Stream 0 is used by cinematic videos and trap_S_StartBackgroundTrack, it can be used for other stuff too (just not at the same time).

Start a (non-looping) 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.

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. Also see another example.

// 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 stream's volume can be changed at any time. For example; controlling the stream volume with a cvar (monitor the vmCvat_t::modificationCount and update volume as needed) or lower the volume during a cut scene. It's probably hard to use this to fade out tracks when they end (due to it going into affect now, not a specified point in the audio track).

// 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 fix time precision loss in the renderer at long uptimes. API change commits for engine and cgame. Time precision loss in the renderer was fixed in this engine commit (3 years after the API change).

Old method of setting it:

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

New method of setting it:

ref->shaderTime = cg.time;

refEntity_t customShader

Like in RTCW, customShader can be used on brush models (func_static, etc).

Spearmint 0.2 (see engine commit) made it so that if customSkin and customShader are used; the surface will only be rendered if skin does not disable it using "nodraw" shader. This makes it so that if a player model has meshes hidden for some skins, they will only have quad damage effect if the skin has them enabled. Using customSkin 0 will use the customShader on all surfaces.

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 this engine commit.