feat(graphics): add real JPEG and transactional texture loading

Author: OmarAglan

.github/workflows/windows-ci.yml

@@ -27,6 +27,7 @@ jobs:
               mingw-w64-ucrt-x86_64-toolchain
               mingw-w64-ucrt-x86_64-cmake
               mingw-w64-ucrt-x86_64-ninja
+              mingw-w64-ucrt-x86_64-libjpeg-turbo
           - name: gcc-release
             configuration: Release
             configure_preset: gcc-release-tests
@@ -38,6 +39,7 @@ jobs:
               mingw-w64-ucrt-x86_64-toolchain
               mingw-w64-ucrt-x86_64-cmake
               mingw-w64-ucrt-x86_64-ninja
+              mingw-w64-ucrt-x86_64-libjpeg-turbo
           - name: clang-debug
             configuration: Debug
             configure_preset: clang-debug-tests
@@ -51,6 +53,7 @@ jobs:
               mingw-w64-ucrt-x86_64-lld
               mingw-w64-ucrt-x86_64-cmake
               mingw-w64-ucrt-x86_64-ninja
+              mingw-w64-ucrt-x86_64-libjpeg-turbo
           - name: clang-release
             configuration: Release
             configure_preset: clang-release-tests
@@ -64,6 +67,7 @@ jobs:
               mingw-w64-ucrt-x86_64-lld
               mingw-w64-ucrt-x86_64-cmake
               mingw-w64-ucrt-x86_64-ninja
+              mingw-w64-ucrt-x86_64-libjpeg-turbo
 
     steps:
       - name: Checkout

AGENTS.md

@@ -5,9 +5,9 @@
 - `Engine/` builds the C++17 `PyramidEngine` library.
 - Active modules are Core, Graphics, Math, Platform, and Utils.
 - `Examples/BasicGame` and `Examples/BasicRendering` are the graphical references.
-- `Tests/PublicApiLinkage.cpp` protects selected public symbols; `Tests/WindowResizeEventTests.cpp` protects resize callback semantics; `Tests/CameraViewportTests.cpp` protects projection resizing; `Tests/FramebufferResizeTests.cpp` protects framebuffer specification and zero-area resize behavior.
+- `Tests/PublicApiLinkage.cpp` protects selected public symbols; `Tests/WindowResizeEventTests.cpp` protects resize callback semantics; `Tests/CameraViewportTests.cpp` protects projection resizing; `Tests/FramebufferResizeTests.cpp` protects framebuffer specification and zero-area resize behavior; `Tests/TextureLoadingTests.cpp` protects transactional file loading and OpenGL upload state.
 - `Tests/Consumer` validates the installed CMake package.
-- `vendor/glad` is a bundled public dependency.
+- `vendor/glad` is a bundled public dependency. libjpeg-turbo is an external open-source dependency resolved through CMake `FindJPEG`.
 - The supported Windows toolchain is MSYS2 UCRT64 with MinGW-w64 GCC; Clang is also validated. Visual Studio is not required.
 - Input, audio, physics, editor, scripting, DirectX, Vulkan, Linux, and macOS are not supported.
 

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to Pyramid Engine are documented here. The project is pre-al
 
 ## [Unreleased]
 
+### Image and texture loading
+
+- Replaced JPEG test-pattern generation with real baseline and progressive JPEG decoding through libjpeg-turbo.
+- Normalized JPEG output to tightly packed RGB pixels and added invalid-data, size-overflow, allocation, and scanline failure handling.
+- Removed the unused custom JPEG entropy/IDCT/color-conversion pipeline and its misleading public headers/tests.
+- Made file-backed OpenGL texture replacement transactional so failed reloads preserve the previous valid GPU object.
+- Added explicit texture load state/error reporting, RGB/RGBA format validation, sRGB internal formats, complete mip-filter mapping, border-color parameters, and unpack-alignment restoration.
+- Added validated baseline/progressive JPEG fixtures and `Graphics.TextureLoading` coverage for upload state, failed reload preservation, and data-size checks.
+- Added libjpeg-turbo to MSYS2 bootstrap, CI, installed package dependencies, and external-consumer resolution.
+
 ### Framebuffer resize safety
 
 - Made `OpenGLFramebuffer::Resize()` transactional so failed replacement creation preserves the last valid framebuffer and attachments.
@@ -44,7 +54,6 @@ All notable changes to Pyramid Engine are documented here. The project is pre-al
 ### Next priorities
 
 - Windows runtime verification for Debug and Release.
-- Real JPEG block decoding.
 - Texture-format and depth-target completion.
 - Scene transform and culling correctness.
 

CMake/PyramidEngineConfig.cmake.in

@@ -2,6 +2,7 @@
 
 include(CMakeFindDependencyMacro)
 find_dependency(OpenGL)
+find_dependency(JPEG)
 
 include("${CMAKE_CURRENT_LIST_DIR}/PyramidEngineTargets.cmake")
 check_required_components(PyramidEngine)

Engine/CMakeLists.txt

@@ -26,9 +26,12 @@ target_include_directories(PyramidEngine
         "${PROJECT_SOURCE_DIR}/vendor"
 )
 
+find_package(JPEG REQUIRED)
+
 target_link_libraries(PyramidEngine
     PUBLIC
         glad
+        JPEG::JPEG
 )
 
 if(WIN32)

Engine/Graphics/include/Pyramid/Graphics/OpenGL/OpenGLTexture.hpp

@@ -1,36 +1,66 @@
 #pragma once
 
 #include "Pyramid/Graphics/Texture.hpp"
-#include <glad/glad.h>
 
-namespace Pyramid {
+#include <glad/glad.h>
 
-class OpenGLTexture2D : public ITexture2D
+namespace Pyramid
 {
-public:
-    OpenGLTexture2D(const TextureSpecification& specification, const void* data);
-    OpenGLTexture2D(const std::string& filepath, bool srgb, bool generateMips);
-    ~OpenGLTexture2D() override;
+    class OpenGLTexture2D final : public ITexture2D
+    {
+    public:
+        OpenGLTexture2D(const TextureSpecification& specification, const void* data);
+        OpenGLTexture2D(const std::string& filepath, bool srgb, bool generateMips);
+        ~OpenGLTexture2D() override;
+
+        OpenGLTexture2D(const OpenGLTexture2D&) = delete;
+        OpenGLTexture2D& operator=(const OpenGLTexture2D&) = delete;
 
-    void Bind(u32 slot = 0) const override;
-    void Unbind(u32 slot = 0) const override;
+        void Bind(u32 slot = 0) const override;
+        void Unbind(u32 slot = 0) const override;
 
-    u32 GetWidth() const override { return m_Specification.Width; }
-    u32 GetHeight() const override { return m_Specification.Height; }
-    u32 GetRendererID() const override { return m_RendererID; }
-    const std::string& GetPath() const override { return m_Filepath; }
+        u32 GetWidth() const override { return m_Specification.Width; }
+        u32 GetHeight() const override { return m_Specification.Height; }
+        u32 GetRendererID() const override { return m_RendererID; }
+        TextureFormat GetFormat() const override { return m_Specification.Format; }
+        const std::string& GetPath() const override { return m_Filepath; }
+        bool IsLoaded() const override { return m_IsLoaded; }
+        std::string GetLastError() const override { return m_LastError; }
 
-    // virtual void SetData(void* data, u32 size) override; // Implement if needed
+        void SetData(const void* data, u32 size) override;
+        void GenerateMipmaps() override;
+        u32 GetMipLevels() const override;
+        bool LoadFromFile(const std::string& filepath, bool srgb = false, bool generateMips = true) override;
 
-private:
-    void Invalidate(const void* data); // Helper to create/recreate texture
-    void SetParameters();
+    private:
+        static bool ResolveFormats(
+            TextureFormat format,
+            bool srgb,
+            GLenum& internalFormat,
+            GLenum& dataFormat,
+            u32& bytesPerPixel);
+        static GLenum ToGLMinFilter(TextureFilter filter, bool hasMipmaps);
+        static GLenum ToGLMagFilter(TextureFilter filter);
+        static GLenum ToGLWrap(TextureWrap wrap);
+        static bool HasMipmapFilter(TextureFilter filter);
 
-    TextureSpecification m_Specification;
-    std::string m_Filepath; // Empty if not loaded from file
-    GLuint m_RendererID = 0;
-    GLenum m_InternalFormat = GL_RGBA8; // Determined from TextureSpecification::Format
-    GLenum m_DataFormat = GL_RGBA;      // Determined from TextureSpecification::Format
-};
+        bool CreateTextureObject(
+            const TextureSpecification& specification,
+            GLenum internalFormat,
+            GLenum dataFormat,
+            const void* data,
+            GLuint& texture,
+            std::string& error) const;
+        void ApplyParameters(const TextureSpecification& specification) const;
+        void SetError(const std::string& error);
 
+        TextureSpecification m_Specification;
+        std::string m_Filepath;
+        std::string m_LastError;
+        GLuint m_RendererID = 0;
+        GLenum m_InternalFormat = GL_RGBA8;
+        GLenum m_DataFormat = GL_RGBA;
+        u32 m_BytesPerPixel = 4;
+        bool m_IsLoaded = false;
+    };
 } // namespace Pyramid

Engine/Graphics/include/Pyramid/Graphics/Texture.hpp

@@ -90,14 +90,14 @@ class ITexture
     virtual std::string GetLastError() const { return ""; }
 
     // Dynamic texture updates (optional - can have default implementations)
-    virtual void SetData(const void* data, u32 size) {}
-    virtual void SetSubData(const void* data, u32 x, u32 y, u32 width, u32 height) {}
+    virtual void SetData(const void*, u32) {}
+    virtual void SetSubData(const void*, u32, u32, u32, u32) {}
 
     // Texture parameters (optional - can have default implementations)
-    virtual void SetFilter(TextureFilter minFilter, TextureFilter magFilter) {}
-    virtual void SetWrap(TextureWrap wrapS, TextureWrap wrapT) {}
-    virtual void SetBorderColor(f32 r, f32 g, f32 b, f32 a) {}
-    virtual void SetMaxAnisotropy(f32 anisotropy) {}
+    virtual void SetFilter(TextureFilter, TextureFilter) {}
+    virtual void SetWrap(TextureWrap, TextureWrap) {}
+    virtual void SetBorderColor(f32, f32, f32, f32) {}
+    virtual void SetMaxAnisotropy(f32) {}
 };
 
 class ITexture2D : public ITexture
@@ -118,8 +118,8 @@ class ITexture2D : public ITexture
     virtual u32 GetMipLevels() const { return 1; }
 
     // Texture streaming and loading (optional implementations)
-    virtual bool LoadFromFile(const std::string& filepath, bool srgb = false, bool generateMips = true) { return false; }
-    virtual bool SaveToFile(const std::string& filepath) const { return false; }
+    virtual bool LoadFromFile(const std::string&, bool = false, bool = true) { return false; }
+    virtual bool SaveToFile(const std::string&) const { return false; }
 };
 
 } // namespace Pyramid