Guide 02

Graphics and sound

How the Xbox-era renderer and audio got onto SDL2, OpenGL and a 5-channel float mixer, and how THUG2's music and voice streams play. All of it came over from the THUG1 port: same engine, same file formats, so THUG2 got its picture and its soundtrack on day one.

GoalSame picture and sound as THUG2's PC release, from its original data files, on a Mac.

The code here was written for the THUG1 port (the diffs are from there) and runs THUG2 unchanged, except for the few format differences the story covers: fonts, skins, animations.

1Render into a backbuffer, present it scaled

The game draws into an off-screen framebuffer at the render resolution; presenting draws that texture as one quad into the window. Everything else (resolution, letterboxing, motion blur) hangs off this.

excerptWn32/Code/Plat/Gfx/p_nx.cpp

// Bind screen FBO (cleared to black for the bars when the window's aspect ratio differs from the backbuffer's)
glBindFramebuffer(GL_FRAMEBUFFER, 0);
glClearColor(0.0f, 0.0f, 0.0f, 1.0f);
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

// Bind backbuffer texture
glActiveTexture(GL_TEXTURE0);
NxWn32::EngineGlobals.backbuffer->BindColorTexture();

// Draw backbuffer quad, scaled to fit the window
NxWn32::SetPresentViewport();
NxWn32::EngineGlobals.fullscreen_quad->Bind();
glDrawElements(GL_TRIANGLES, 6, GL_UNSIGNED_SHORT, nullptr);

SDL_GL_SwapWindow(NxWn32::EngineGlobals.window);

Training: the backbuffer drawn as one quad, scaled into the window.

In the air in Training. — Motion blur reuses the previous frame from the same backbuffer.

2Decode console-flavoured textures

Xbox textures are swizzled (Morton order) and fonts are 8-bit palettized. They're unswizzled and expanded to RGBA before glTexImage2D. THUG2's 2D sprites add one more twist: their rows are stored bottom-up.

excerptWn32/Code/Plat/Gfx/nx/chars.cpp

// Decode palettized texture
for( i = 0; i < NumBytes; ++i )
{
	uint8 *p = p_clut[*p_texel_data_p++];
	*p_texture_p++ = p[0];
	*p_texture_p++ = p[1];
	*p_texture_p++ = p[2];
	*p_texture_p++ = (p[3] >= 0x80) ? 0xFF : (p[3] * 2); // Alpha is halved, PS2 remnant?
}
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, Width, Height, 0, GL_RGBA, GL_UNSIGNED_BYTE, p_texture);

PS2 alpha goes 0–128, because 128 means "fully opaque" on the GS. Twenty years later we're still multiplying by two.

3One mixer for everything

A single SDL audio callback at 48 kHz, 5 float channels: music and voice streams first, sound effects on top. Locks around it keep the game thread from swapping streams mid-buffer.

excerptWn32/Code/Plat/Audio/Mixer.cpp

void AudioCallback(void *userdata, Uint8 *stream, int len)
{
	std::fill((float*)stream, (float*)(stream + len), 0.0f);
	Pcm::PCMAudio_Mix((char*)stream, len);     // music + streams
	Sfx::MixSoundFX((char*)stream, len);        // sound effects
}

SDL_AudioSpec s_wanted_spec = {};
s_wanted_spec.format = AUDIO_F32SYS;
s_wanted_spec.freq = 48000;
s_wanted_spec.channels = 5;
s_wanted_spec.samples = 1024;
s_wanted_spec.callback = AudioCallback;

excerptWn32/Code/Plat/Gel/SoundFX/p_sfx.cpp

static constexpr float SOUND_VOLUME = 0.5f; // PC sounds are much too loud

4The soundtrack starts itself

THUG1's retail scripts only queue the soundtrack when running from CD, so the THUG1 port needed a script patch to switch it on. THUG2's main menu starts the playlist itself (PlaySongsRandomly in launch_main_menu; the log says shuffling random song order num_songs=53), so that patch stayed behind.

5Find the tracks: hex names and a .wad

THUG2's PC release does it the same way as THUG1's: music files named after the checksum of the track name, in hex (04df1461.bik and 136 more in streams/music), voice streams packed into streams/pcm/pcm.wad, indexed by pcm.dat.

diffWn32/Code/Plat/Gel/Music/p_music.cpp · THUG1 port

@@ -205,14 +350,51 @@ namespace Pcm
+				// The PC version's files are named after the checksum of the track name in hex (e.g. a9a6af00.bik)
 				std::string name = i.path().stem().string();
-				uint32 checksum = Crc::GenerateCRCFromString(name.c_str());
+				uint32 checksum;
+				if (name.size() == 8 && name.find_first_not_of("0123456789abcdefABCDEF") == std::string::npos)
+					checksum = (uint32)std::stoul(name, nullptr, 16);
+				else
+					checksum = Crc::GenerateCRCFromString(name.c_str());
@@
+	static void IndexWad(const std::filesystem::path &dat, const std::filesystem::path &wad)
+	{
+		// pcm.dat: the number of streams, then the checksum of the name, offset and size of each one's .bik
+		std::ifstream file(dat, std::ios::binary);
+		uint32 count = 0;
+		if (!file.read((char*)&count, sizeof(count)))
+			return;
+
+		for (uint32 i = 0; i < count; i++)
+		{
+			uint32 entry[3];
+			if (!file.read((char*)entry, sizeof(entry)))
+				break;
+			wad_streams[entry[0]] = { entry[1], entry[2] };
+		}
+		wad_path = wad;
+	}

6Decode Bink audio, resample, spread over 5 channels

A built-in Bink audio decoder (binkaudio.cpp) feeds a streamer that resamples to 48 kHz (with pitch, because the game bends voice pitch) and places stereo on the 5 mixer channels the way sound effects do.

diffWn32/Code/Plat/Gel/Music/p_music.cpp · THUG1 port

@@ -171,6 +173,140 @@ namespace Pcm
+	// Decoder for the PC version's music and streams: the audio of the .bik files in Data/streams/music,
+	// and of the ones packed in Data/streams/pcm/pcm.wad
+	class BinkDecoder : public Streamer
+	{
+			// Pitch in percent
+			void SetPitch(float pitch) override
+			{
+				if (valid && pitch > 0.0f)
+					step = pitch / 100.0 * bink.GetSampleRate() / 48000.0;
+			}
+
+				float l = frame_a[0] + (frame_b[0] - frame_a[0]) * (float)position;
+				float r = frame_a[1] + (frame_b[1] - frame_a[1]) * (float)position;
+				position += step;
+
+				// Spread over the 5 mixer channels the same way sound effects place their left and
+				// right volumes (Sfx::SetVoiceParameters)
+				*out++ = l;
+				*out++ = r;
+				*out++ = (l + r) * 0.5f;
+				*out++ = l * 0.5f;
+				*out++ = r * 0.5f;
+	};
@@ -639,8 +824,12 @@ namespace Pcm
 	bool PCMAudio_SetStreamPitch( float fPitch, int whichStream )
 	{
-		(void)fPitch;
-		(void)whichStream;
+		Audio::Lock();
+
+		if (stream_stream[whichStream] != nullptr)
+			stream_stream[whichStream]->SetPitch(fPitch);
+
+		Audio::Unlock();
 		return true;
 	}

(void)fPitch; is a stub's way of saying "I heard you, I just don't care". Now it cares.

FOR EDUCATION PURPOSES ONLY. Screenshots are captured from the port running the reader's own copy of the game. The diffs are trimmed to the interesting lines (unchanged context is cut, marked ⋯); the repository has the full changes. Paths are relative to the THUG2/ folder.