feat(screenshot): Add threaded JPEG/PNG screenshots without game stalls

CMakeLists.txt

@@ -65,6 +65,7 @@ endif()
 include(cmake/config.cmake)
 include(cmake/gamespy.cmake)
 include(cmake/lzhl.cmake)
+include(cmake/stb.cmake)
 
 if (IS_VS6_BUILD)
     # The original max sdk does not compile against a modern compiler.

Core/GameEngine/Include/Common/OptionPreferences.h

@@ -72,6 +72,7 @@ class OptionPreferences : public UserPreferences
 	Bool getRightMouseScrollWithAlternateMouseEnabled() const;
 	Bool getRetaliationModeEnabled();
 	Bool getDoubleClickAttackMoveEnabled();
+	Int getJPEGQuality() const;
 	Real getScrollFactor();
 	Bool getDrawScrollAnchor();
 	Bool getMoveScrollAnchor();

Core/GameEngine/Include/GameClient/Display.h

@@ -33,6 +33,14 @@
 #include "GameClient/GameFont.h"
 #include "GameClient/View.h"
 
+enum ScreenshotFormat
+{
+	SCREENSHOT_JPEG,
+	SCREENSHOT_PNG,
+
+	SCREENSHOT_FORMAT_COUNT
+};
+
 struct ShroudLevel
 {
 	Short m_currentShroud;		///< A Value of 1 means shrouded.  0 is not.  Negative is the count of people looking.
@@ -172,7 +180,7 @@ class Display : public SubsystemInterface
 	virtual void preloadModelAssets( AsciiString model ) = 0;	///< preload model asset
 	virtual void preloadTextureAssets( AsciiString texture ) = 0;	///< preload texture asset
 
-	virtual void takeScreenShot() = 0;										///< saves screenshot to a file
+	virtual void takeScreenShot(ScreenshotFormat format, Int jpegQuality = 80) = 0;			///< saves screenshot in specified format
 	virtual void toggleMovieCapture() = 0;							///< starts saving frames to an avi or frame sequence
 	virtual void toggleLetterBox() = 0;										///< enabled letter-boxed display
 	virtual void enableLetterBox(Bool enable) = 0;						///< forces letter-boxed display on/off

Core/GameEngine/Source/Common/OptionPreferences.cpp

@@ -239,6 +239,18 @@ Bool OptionPreferences::getDoubleClickAttackMoveEnabled()
 	return FALSE;
 }
 
+Int OptionPreferences::getJPEGQuality() const
+{
+	OptionPreferences::const_iterator it = find("JPEGQuality");
+	if (it == end())
+		return 80;
+
+	// TheSuperHackers @feature bobtista 08/07/2026 Cap the quality at 95, because JPEG quality
+	// above that increases the file size significantly with no visible benefit.
+	Int quality = atoi(it->second.str());
+	return clamp(1, quality, 95);
+}
+
 Real OptionPreferences::getScrollFactor()
 {
 	OptionPreferences::const_iterator it = find("ScrollFactor");

Core/GameEngine/Source/GameClient/MessageStream/CommandXlat.cpp

@@ -3738,7 +3738,15 @@ GameMessageDisposition CommandTranslator::translateGameMessage(const GameMessage
 		case GameMessage::MSG_META_TAKE_SCREENSHOT:
 		{
 			if (TheDisplay)
-				TheDisplay->takeScreenShot();
+				TheDisplay->takeScreenShot(SCREENSHOT_JPEG, TheGlobalData->m_jpegQuality);
+			disp = DESTROY_MESSAGE;
+			break;
+		}
+
+		case GameMessage::MSG_META_TAKE_SCREENSHOT_PNG:
+		{
+			if (TheDisplay)
+				TheDisplay->takeScreenShot(SCREENSHOT_PNG);
 			disp = DESTROY_MESSAGE;
 			break;
 		}

Core/GameEngine/Source/GameClient/MessageStream/MetaEvent.cpp

@@ -171,6 +171,7 @@ static const LookupListRec GameMessageMetaTypeNames[] =
 	{ "END_PREFER_SELECTION",											GameMessage::MSG_META_END_PREFER_SELECTION },
 
 	{ "TAKE_SCREENSHOT",													GameMessage::MSG_META_TAKE_SCREENSHOT },
+	{ "TAKE_SCREENSHOT_PNG",											GameMessage::MSG_META_TAKE_SCREENSHOT_PNG },
 	{ "ALL_CHEER",																GameMessage::MSG_META_ALL_CHEER },
 
 	{ "BEGIN_CAMERA_ROTATE_LEFT",									GameMessage::MSG_META_BEGIN_CAMERA_ROTATE_LEFT },
@@ -945,6 +946,26 @@ void MetaMap::generateMetaMap()
 			map->m_usableIn = COMMANDUSABLE_GAME;
 		}
 	}
+	{
+		MetaMapRec *map = TheMetaMap->getMetaMapRec(GameMessage::MSG_META_TAKE_SCREENSHOT);
+		if (map->m_key == MK_NONE)
+		{
+			map->m_key = MK_F12;
+			map->m_transition = DOWN;
+			map->m_modState = NONE;
+			map->m_usableIn = COMMANDUSABLE_EVERYWHERE;
+		}
+	}
+	{
+		MetaMapRec *map = TheMetaMap->getMetaMapRec(GameMessage::MSG_META_TAKE_SCREENSHOT_PNG);
+		if (map->m_key == MK_NONE)
+		{
+			map->m_key = MK_F12;
+			map->m_transition = DOWN;
+			map->m_modState = CTRL;
+			map->m_usableIn = COMMANDUSABLE_EVERYWHERE;
+		}
+	}
 
 #if defined(RTS_DEBUG)
 	{

Core/GameEngineDevice/CMakeLists.txt

@@ -73,6 +73,7 @@ set(GAMEENGINEDEVICE_SRC
     Include/W3DDevice/GameClient/W3DTreeBuffer.h
     Include/W3DDevice/GameClient/W3DVideoBuffer.h
     Include/W3DDevice/GameClient/W3DView.h
+    Include/W3DDevice/GameClient/W3DScreenshot.h
 #    Include/W3DDevice/GameClient/W3DVolumetricShadow.h
     Include/W3DDevice/GameClient/W3DWater.h
     Include/W3DDevice/GameClient/W3DWaterTracks.h
@@ -175,6 +176,8 @@ set(GAMEENGINEDEVICE_SRC
     Source/W3DDevice/GameClient/W3DTreeBuffer.cpp
     Source/W3DDevice/GameClient/W3DVideoBuffer.cpp
     Source/W3DDevice/GameClient/W3DView.cpp
+    Source/W3DDevice/GameClient/W3DScreenshot.cpp
+    Source/W3DDevice/GameClient/stb_image_write_impl.cpp
 #    Source/W3DDevice/GameClient/W3dWaypointBuffer.cpp
 #    Source/W3DDevice/GameClient/W3DWebBrowser.cpp
     Source/W3DDevice/GameClient/Water/W3DWater.cpp
@@ -220,6 +223,7 @@ target_include_directories(corei_gameenginedevice_public INTERFACE
 target_link_libraries(corei_gameenginedevice_private INTERFACE
     corei_always
     corei_main
+    stb
 )
 
 target_link_libraries(corei_gameenginedevice_public INTERFACE

Core/GameEngineDevice/Include/W3DDevice/GameClient/W3DScreenshot.h

@@ -0,0 +1,24 @@
+/*
+**	Command & Conquer Generals Zero Hour(tm)
+**	Copyright 2025 TheSuperHackers
+**
+**	This program is free software: you can redistribute it and/or modify
+**	it under the terms of the GNU General Public License as published by
+**	the Free Software Foundation, either version 3 of the License, or
+**	(at your option) any later version.
+**
+**	This program is distributed in the hope that it will be useful,
+**	but WITHOUT ANY WARRANTY; without even the implied warranty of
+**	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+**	GNU General Public License for more details.
+**
+**	You should have received a copy of the GNU General Public License
+**	along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+#pragma once
+
+#include "GameClient/Display.h"
+
+void W3D_TakeCompressedScreenshot(ScreenshotFormat format, Int jpegQuality);
+

Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DScreenshot.cpp

@@ -0,0 +1,216 @@
+/*
+**	Command & Conquer Generals Zero Hour(tm)
+**	Copyright 2025 TheSuperHackers
+**
+**	This program is free software: you can redistribute it and/or modify
+**	it under the terms of the GNU General Public License as published by
+**	the Free Software Foundation, either version 3 of the License, or
+**	(at your option) any later version.
+**
+**	This program is distributed in the hope that it will be useful,
+**	but WITHOUT ANY WARRANTY; without even the implied warranty of
+**	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+**	GNU General Public License for more details.
+**
+**	You should have received a copy of the GNU General Public License
+**	along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include "W3DDevice/GameClient/W3DScreenshot.h"
+#include "Common/GlobalData.h"
+#include "GameClient/GameText.h"
+#include "GameClient/InGameUI.h"
+#include "WW3D2/dx8wrapper.h"
+#include "WW3D2/surfaceclass.h"
+#include <stb_image_write.h>
+
+struct ScreenshotThreadData
+{
+	ScreenshotThreadData()
+		: pixelData(nullptr)
+	{
+	}
+
+	~ScreenshotThreadData()
+	{
+		delete [] pixelData;
+	}
+
+	unsigned char* pixelData;
+	unsigned int width;
+	unsigned int height;
+	bool is16Bit;
+	char userDataDirectory[_MAX_PATH];
+	char leafname[_MAX_FNAME];
+	int quality;
+	ScreenshotFormat format;
+};
+
+static DWORD WINAPI screenshotThreadFunc(LPVOID param)
+{
+	ScreenshotThreadData* data = (ScreenshotThreadData*)param;
+
+	// TheSuperHackers @feature bobtista 08/07/2026 Save screenshots into a Screenshots subfolder
+	// to keep the user data root folder tidy.
+	char pathname[_MAX_PATH];
+	strlcpy(pathname, data->userDataDirectory, ARRAY_SIZE(pathname));
+	strlcat(pathname, "Screenshots\\", ARRAY_SIZE(pathname));
+	CreateDirectory(pathname, nullptr);
+	strlcat(pathname, data->leafname, ARRAY_SIZE(pathname));
+
+	const unsigned int width = data->width;
+	const unsigned int height = data->height;
+	unsigned int x, y, index;
+
+	// Convert to R8G8B8 for stb_image_write.
+	unsigned char* image = new unsigned char[3 * width * height];
+
+	if (!data->is16Bit)
+	{
+		// Convert A8R8G8B8/X8R8G8B8 to R8G8B8
+		for (y = 0; y < height; y++)
+		{
+			const unsigned char* srcLine = data->pixelData + y * width * 4;
+			for (x = 0; x < width; x++)
+			{
+				index = 3 * (x + y * width);
+				image[index + 0] = srcLine[4 * x + 2];
+				image[index + 1] = srcLine[4 * x + 1];
+				image[index + 2] = srcLine[4 * x + 0];
+			}
+		}
+	}
+	else
+	{
+		// Convert R5G6B5 to R8G8B8
+		for (y = 0; y < height; y++)
+		{
+			const unsigned short* srcLine = (const unsigned short*)(data->pixelData + y * width * 2);
+			for (x = 0; x < width; x++)
+			{
+				const unsigned short rgb = srcLine[x];
+				index = 3 * (x + y * width);
+				image[index + 0] = (unsigned char)((rgb & 0xF800) >> 8);
+				image[index + 1] = (unsigned char)((rgb & 0x07E0) >> 3);
+				image[index + 2] = (unsigned char)((rgb & 0x001F) << 3);
+			}
+		}
+	}
+
+	int success = 0;
+	switch (data->format)
+	{
+		case SCREENSHOT_JPEG:
+			success = stbi_write_jpg(pathname, width, height, 3, image, data->quality);
+			break;
+		case SCREENSHOT_PNG:
+			success = stbi_write_png(pathname, width, height, 3, image, width * 3);
+			break;
+	}
+
+	if (!success)
+	{
+		DEBUG_LOG(("Failed to write screenshot %s", pathname));
+	}
+
+	delete [] image;
+	delete data;
+
+	return success;
+}
+
+void W3D_TakeCompressedScreenshot(ScreenshotFormat format, Int jpegQuality)
+{
+	static const char* const ScreenshotFormatExtensions[] = { "jpg", "png" };
+	static_assert(ARRAY_SIZE(ScreenshotFormatExtensions) == SCREENSHOT_FORMAT_COUNT, "Incorrect array size");
+
+	// The filename is created here because the success message below shows it.
+	char leafname[_MAX_FNAME];
+	const char* extension = ScreenshotFormatExtensions[format];
+
+	SYSTEMTIME st;
+	GetLocalTime(&st);
+	sprintf(leafname, "sshot_%04d%02d%02d_%02d%02d%02d_%03d.%s",
+		st.wYear, st.wMonth, st.wDay, st.wHour, st.wMinute, st.wSecond, st.wMilliseconds, extension);
+
+	// TheSuperHackers @bugfix xezon 21/05/2025 Get the back buffer and create a copy of the surface.
+	// Originally this code took the front buffer and tried to lock it. This does not work when the
+	// render view clips outside the desktop boundaries. It crashed the game.
+	SurfaceClass* surface = DX8Wrapper::_Get_DX8_Back_Buffer();
+	SurfaceClass::SurfaceDescription surfaceDesc;
+	surface->Get_Description(surfaceDesc);
+
+	// TheSuperHackers @bugfix bobtista 08/07/2026 Support the 16 bit back buffer format that the
+	// game uses when running in 16 bit color mode. Reading it with the 32 bit stride read garbage.
+	const bool is32Bit = surfaceDesc.Format == WW3D_FORMAT_A8R8G8B8 || surfaceDesc.Format == WW3D_FORMAT_X8R8G8B8;
+	const bool is16Bit = surfaceDesc.Format == WW3D_FORMAT_R5G6B5;
+
+	if (!is32Bit && !is16Bit)
+	{
+		DEBUG_LOG(("Screenshot does not support back buffer format %d", (int)surfaceDesc.Format));
+		surface->Release_Ref();
+		return;
+	}
+
+	SurfaceClass* surfaceCopy = NEW_REF(SurfaceClass, (DX8Wrapper::_Create_DX8_Surface(surfaceDesc.Width, surfaceDesc.Height, surfaceDesc.Format)));
+	DX8Wrapper::_Copy_DX8_Rects(surface->Peek_D3D_Surface(), nullptr, 0, surfaceCopy->Peek_D3D_Surface(), nullptr);
+
+	surface->Release_Ref();
+	surface = nullptr;
+
+	struct Rect
+	{
+		int Pitch;
+		void* pBits;
+	} lrect;
+
+	lrect.pBits = surfaceCopy->Lock(&lrect.Pitch);
+	if (lrect.pBits == nullptr)
+	{
+		surfaceCopy->Release_Ref();
+		return;
+	}
+
+	unsigned int y;
+	unsigned int width = surfaceDesc.Width;
+	unsigned int height = surfaceDesc.Height;
+
+	// Copy the surface rows into a tightly packed buffer. The pixel conversion and all file
+	// operations are done on the screenshot thread to keep the main thread cheap.
+	const unsigned int bytesPerPixel = is32Bit ? 4 : 2;
+	unsigned char* pixels = new unsigned char[bytesPerPixel * width * height];
+
+	for (y = 0; y < height; y++)
+	{
+		memcpy(pixels + y * width * bytesPerPixel, (const unsigned char*)lrect.pBits + y * lrect.Pitch, width * bytesPerPixel);
+	}
+
+	surfaceCopy->Unlock();
+	surfaceCopy->Release_Ref();
+	surfaceCopy = nullptr;
+
+	ScreenshotThreadData* threadData = new ScreenshotThreadData();
+	threadData->pixelData = pixels;
+	threadData->width = width;
+	threadData->height = height;
+	threadData->is16Bit = is16Bit;
+	threadData->quality = jpegQuality;
+	threadData->format = format;
+	strlcpy(threadData->userDataDirectory, TheGlobalData->getPath_UserData().str(), ARRAY_SIZE(threadData->userDataDirectory));
+	strlcpy(threadData->leafname, leafname, ARRAY_SIZE(threadData->leafname));
+
+	DWORD threadId;
+	HANDLE hThread = CreateThread(nullptr, 0, screenshotThreadFunc, threadData, 0, &threadId);
+	if (hThread)
+	{
+		CloseHandle(hThread);
+
+		UnicodeString ufileName;
+		ufileName.translate(leafname);
+		TheInGameUI->message(TheGameText->fetch("GUI:ScreenCapture"), ufileName.str());
+	}
+	else
+	{
+		delete threadData;
+	}
+}

Core/GameEngineDevice/Source/W3DDevice/GameClient/stb_image_write_impl.cpp

@@ -0,0 +1,21 @@
+/*
+**	Command & Conquer Generals(tm)
+**	Copyright 2025 TheSuperHackers
+**
+**	This program is free software: you can redistribute it and/or modify
+**	it under the terms of the GNU General Public License as published by
+**	the Free Software Foundation, either version 3 of the License, or
+**	(at your option) any later version.
+**
+**	This program is distributed in the hope that it will be useful,
+**	but WITHOUT ANY WARRANTY; without even the implied warranty of
+**	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+**	GNU General Public License for more details.
+**
+**	You should have received a copy of the GNU General Public License
+**	along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+#define STB_IMAGE_WRITE_IMPLEMENTATION
+#include <stb_image_write.h>
+