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,16 @@
 #include "GameClient/GameFont.h"
 #include "GameClient/View.h"
 
+enum ScreenshotFormat
+{
+	SCREENSHOT_JPEG,
+	SCREENSHOT_PNG,
+
+	SCREENSHOT_FORMAT_COUNT
+};
+
+constexpr const Int DEFAULT_JPEG_QUALITY = 80;
+
 struct ShroudLevel
 {
 	Short m_currentShroud;		///< A Value of 1 means shrouded.  0 is not.  Negative is the count of people looking.
@@ -172,7 +182,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 = DEFAULT_JPEG_QUALITY) = 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

@@ -38,6 +38,7 @@
 #include "Common/OptionPreferences.h"
 
 #include "GameClient/ClientInstance.h"
+#include "GameClient/Display.h"
 #include "GameClient/LookAtXlat.h"
 #include "GameClient/Mouse.h"
 
@@ -239,6 +240,18 @@ Bool OptionPreferences::getDoubleClickAttackMoveEnabled()
 	return FALSE;
 }
 
+Int OptionPreferences::getJpegQuality() const
+{
+	OptionPreferences::const_iterator it = find("JpegQuality");
+	if (it == end())
+		return DEFAULT_JPEG_QUALITY;
+
+	// TheSuperHackers @info bobtista 14/07/2026 Clamp the quality to 50-95: above 95 the file
+	// size increases significantly with no visible benefit, below 50 the image degrades visibly.
+	const Int quality = atoi(it->second.str());
+	return clamp(50, quality, 95);
+}
+
 Real OptionPreferences::getScrollFactor()
 {
 	OptionPreferences::const_iterator it = find("ScrollFactor");

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

@@ -3737,7 +3737,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,28 @@
+/*
+**	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);
+
+// Called once per frame on the main thread to show messages for screenshots
+// that the screenshot thread has finished writing.
+void W3D_UpdateScreenshotMessages();
+