diff --git a/Romeo/docs/Juliet_include_Core_Application_ApplicationManager.md b/Romeo/docs/Juliet_include_Core_Application_ApplicationManager.md index a74243f..d4a5149 100644 --- a/Romeo/docs/Juliet_include_Core_Application_ApplicationManager.md +++ b/Romeo/docs/Juliet_include_Core_Application_ApplicationManager.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\Application\ApplicationManager.cpp` ## AI Description -The ApplicationManager initializes and manages the execution lifecycle of applications by sequentially orchestrating engine initialization, application loading, core runtime operations, cleanup unloading, and final shutdown within a defined flag context. +The `ApplicationManager` class in the Juliet project is designed to manage the lifecycle of an application. It encapsulates the initialization, loading, running, unloading, and shutdown processes for a given application instance. The `StartApplication` function orchestrates these steps by calling various helper functions within the `Juliet` namespace, such as `InitializeEngine`, `LoadApplication`, `RunEngine`, `UnloadApplication`, and `ShutdownEngine`. This class provides a structured approach to managing the application's lifecycle, ensuring that all necessary resources are properly initialized, loaded, executed, and cleaned up. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Application_IApplication.md b/Romeo/docs/Juliet_include_Core_Application_IApplication.md index 30df9d4..24d41c1 100644 --- a/Romeo/docs/Juliet_include_Core_Application_IApplication.md +++ b/Romeo/docs/Juliet_include_Core_Application_IApplication.md @@ -4,7 +4,15 @@ - Header: `Juliet\include\Core\Application\IApplication.h` ## AI Description -Juliet's IApplication is an abstract base class defining the engine lifecycle and system interfaces. Its purpose manages initialization, runtime status, rendering callbacks, device accessors, and debug utilities like swapchain info via nonnull pointers to core render structures. Design enforces platform-specific application logic through required virtual methods for setup, updates, and frame-based events within the Juliet graphics architecture. +The `IApplication` class in the provided C++ component serves as a central interface for managing the lifecycle of an application. It encapsulates the core functionalities required to initialize, shutdown, and update the application state. The class provides methods for accessing engine systems such as the platform window and graphics device. + +Key features include: +- Initialization and shutdown methods (`Init` and `Shutdown`) that manage resources and clean up. +- Update method (`Update`) where game logic is executed. +- Accessors for engine systems like the platform window and graphics device. +- Render lifecycle methods (`OnPreRender`, `OnRender`, `GetColorTargetInfo`, `GetDepthTargetInfo`, and `GetDebugCamera`) that handle rendering tasks. + +This design ensures that all application components are managed efficiently, facilitating a smooth and organized development process. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Common_CRC32.md b/Romeo/docs/Juliet_include_Core_Common_CRC32.md index 7a45b3a..45693e2 100644 --- a/Romeo/docs/Juliet_include_Core_Common_CRC32.md +++ b/Romeo/docs/Juliet_include_Core_Common_CRC32.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\Common\CRC32.h` ## AI Description -The Juliet CRC32 component computes a 32-bit cyclic redundancy check for C-strings using the MIT implementation. It offers two constexpr functions: one returning `uint32_t` and another providing string literal suffix support, both supporting compile-time constant evaluation via templates. The design includes an optimized lookup table precomputed in the details namespace to enable fast hardware-friendly execution without runtime function calls. +The `CRC32.h` header file in the Juliet library provides a constant-time CRC-32 checksum calculation function. The `crc32` function takes a pointer to a string and its length as input and returns the corresponding CRC-32 checksum value. The `operator""_crc32` is a constexpr operator that allows for easy usage of the CRC-32 checksum in constant expressions, such as in template arguments or initialization lists. This makes it convenient to integrate CRC-32 checksums into various parts of the Juliet library without needing to manually calculate them. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Common_CoreTypes.md b/Romeo/docs/Juliet_include_Core_Common_CoreTypes.md index 4bb2e53..1248db4 100644 --- a/Romeo/docs/Juliet_include_Core_Common_CoreTypes.md +++ b/Romeo/docs/Juliet_include_Core_Common_CoreTypes.md @@ -4,7 +4,32 @@ - Header: `Juliet\include\Core\Common\CoreTypes.h` ## AI Description -Provides standard type aliases and constexpr limits in CoreTypes.h. Defines byte operations, memory buffers via ByteBuffer struct, pointer types for null safety, and compile-time maximums using template specialization within the Common module namespace architecture. +The `CoreTypes.h` header file in the Juliet project is designed to provide a unified set of fundamental data types and utilities for common operations such as byte manipulation, size calculations, and limits. The primary purpose of this component is to ensure consistency and ease of use across different parts of the application by providing clear and standardized definitions for basic data types like `uint8`, `int8`, `size_t`, etc. + +The header file includes several key components: + +1. **Data Types**: + - `Byte`: A byte type aliasing `std::byte` from the C++ Standard Library, which is a portable way to represent bytes. + - `uint8`, `uint16`, `uint32`, `uint64`: Aliases for unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, respectively. These types are used for representing data in various formats such as network packets or file sizes. + - `int8`, `int16`, `int32`, `int64`: Aliases for signed 8-bit, 16-bit, 32-bit, and 64-bit integers. These types are suitable for handling integer values in applications that require signed data. + +2. **Size and Index Types**: + - `size_t` and `index_t`: Aliasing `std::size_t` from the C++ Standard Library, which is a type used to represent the size of objects or collections. This type ensures that all sizes are handled consistently across different platforms. + - These types are used for indexing arrays, managing memory allocations, and other operations where size information is crucial. + +3. **ByteBuffer**: + - A struct `ByteBuffer` is defined to encapsulate a byte buffer along with its size. This structure is useful for handling binary data efficiently in applications that require dynamic memory management or serialization/deserialization of data. + +4. **Function Pointer Type**: + - A function pointer type `FunctionPtr` is defined using `auto (*)(void) -? void`. This type is used to represent pointers to functions that take no arguments and return void, which is commonly used for callbacks or event handlers in applications. + +5. **Limits Calculation Functions**: + - The `MaxValueOf?Type?` template function calculates the maximum value that can be represented by a given integer type using `std::numeric_limits`. This utility function simplifies the process of finding the upper limit of different data types, making it easier to handle and validate data within the application. + +6. **Size Conversion Macros**: + - The macros `Kilobytes` and `Megabytes` are defined to convert between kilobytes and megabytes. These macros provide a convenient way to perform size calculations without having to manually multiply by 1024 each time. + +The design of this header file is aimed at promoting consistency in data types across the project, ensuring that all parts of ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Common_CoreUtils.md b/Romeo/docs/Juliet_include_Core_Common_CoreUtils.md index 06466b8..3c7e436 100644 --- a/Romeo/docs/Juliet_include_Core_Common_CoreUtils.md +++ b/Romeo/docs/Juliet_include_Core_Common_CoreUtils.md @@ -5,7 +5,29 @@ - Source: `Juliet\src\Core\Common\CoreUtils.cpp` ## AI Description -Juliet CoreUtils provides portable macros for stringification, compiler-specific pragmas, assertions with source locations, and error handling. It includes a deferred function template, byte manipulation utilities, alignment helpers, swap operations, and cross-platform crash mechanisms via platform breakers or trap functions tailored to Clang/GCC or MSVC. +This C++ component provides a collection of utility functions and macros designed to enhance the robustness, performance, and debugging capabilities of applications. The primary purpose is to simplify common tasks such as stringification, pragma handling, assertion checks, memory management, and more. + +The design includes several key features: + +1. **Stringify Helpers**: Macros like `JULIET_STR` and `JULIET_TOSTRING` are used to convert C++ literals into strings at compile time, which is particularly useful for logging and debugging purposes. + +2. **Pragma Operator**: The `JULIET_PRAGMA` macro allows for conditional compilation based on the compiler being used. This includes suppressing warnings and errors specific to MSVC and Clang compilers. + +3. **Agnostic "Push/Pop"**: The `JULIET_WARNING_PUSH` and `JULIET_WARNING_POP` macros are used to manage compiler warnings during macro expansion, ensuring that only the necessary warnings are suppressed. + +4. **Assert Macros**: The `Assert`, `AssertHR`, and `Unimplemented` macros provide a consistent way to assert conditions in the code. They include additional information such as the source location and handle result for better debugging. + +5. **Zeroing Functions**: The `ZeroStruct`, `ZeroArray`, and `ZeroDynArray` functions are used to zero out memory, ensuring that any uninitialized data is properly cleaned up. + +6. **Deferred Function Handling**: The `DeferredFunction` class allows for deferred execution of functions, which can be useful in scenarios where the function needs to be executed after a certain condition is met. + +7. **Alignment and Swap Functions**: The `AlignPow2`, `Swap`, and `AlignOf` macros provide utilities for aligning memory addresses and swapping values between variables. + +8. **Compiler Detection**: The `COMPILER_CLANG` and `COMPILER_MSVC` macros are used to detect the compiler being used, allowing for conditional compilation based on the specific compiler features available. + +9. **Memory Management**: The `Free` function ensures that a `ByteBuffer` is properly deallocated, freeing up memory resources. + +This component aims to provide a comprehensive set of tools for developers to enhance their code quality and performance, while maintaining a clean and maintainable structure. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Common_EnumUtils.md b/Romeo/docs/Juliet_include_Core_Common_EnumUtils.md index 88f2b07..4ef6ff0 100644 --- a/Romeo/docs/Juliet_include_Core_Common_EnumUtils.md +++ b/Romeo/docs/Juliet_include_Core_Common_EnumUtils.md @@ -4,7 +4,11 @@ - Header: `Juliet\include\Core\Common\EnumUtils.h` ## AI Description -The `Juliet` library defines a C++20 concept to identify enums and provides template operations including bit-wise inversion, bitwise AND/OR/XOR with compound assignment. It also implements addition/subtraction between enum types or their underlying integer representations via the standard traits type system for portable manipulation of enum flags in Juliet architecture. +The `EnumUtils.h` header file in the Juliet project provides a collection of utility functions for working with enums in C++. The primary purpose is to provide a set of operators that allow for bitwise operations, arithmetic operations, and conversion between enum values and their underlying integer representations. This makes it easier to manipulate enum values programmatically without having to manually cast them between different types. + +The `IsEnum` concept checks if a type is an enum, ensuring that the template functions only operate on valid enum types. The provided operators include bitwise NOT (`~`), OR (`|`), AND (`?`), XOR (`^`), and subtraction (`-`). Additionally, there are overloaded assignment operators for each of these operations to allow chaining assignments. + +The `ToUnderlying` function converts an enum value to its underlying integer representation, while the `ToEnum` function converts an integer back to the corresponding enum value. These utility functions simplify common tasks related to enum manipulation in C++, making the code more readable and maintainable. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Common_NonCopyable.md b/Romeo/docs/Juliet_include_Core_Common_NonCopyable.md index 44c9b67..7f779d8 100644 --- a/Romeo/docs/Juliet_include_Core_Common_NonCopyable.md +++ b/Romeo/docs/Juliet_include_Core_Common_NonCopyable.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\Common\NonCopyable.h` ## AI Description -The Juliet::NonCopyable class in the Core/Common module prevents copying operations by deleting copy constructors and assignment operators, ensuring base classes cannot be instantiated or copied directly. +The `NonCopyable` class in the Juliet library is designed to prevent instances of a class from being copied. This is achieved by deleting the copy constructor and assignment operator, which are public members of the class. By doing so, we ensure that any attempt to create a copy of an instance of `NonCopyable` will result in a compilation error, thereby enforcing immutability or preventing unintended modifications to the object. This design pattern is particularly useful for classes that represent immutable data structures or objects where copying would lead to unexpected behavior. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Common_NonMovable.md b/Romeo/docs/Juliet_include_Core_Common_NonMovable.md index b8ef57f..533b553 100644 --- a/Romeo/docs/Juliet_include_Core_Common_NonMovable.md +++ b/Romeo/docs/Juliet_include_Core_Common_NonMovable.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\Common\NonMovable.h` ## AI Description -The Julian NonMovable class prevents copying and assignment by explicitly deleting move constructors, constant-move operators, copy constructor, and default assignments. It provides a base for non-copyable types within the Juliet library while retaining destructibility through virtual deletion in its interface design. +The `NonMovable` class in the Juliet project is designed to prevent instances of this class from being copied or moved. This is achieved by using the C++11 move semantics and deleting the copy constructor and assignment operator. The class ensures that any attempt to create a copy or move of an instance will result in a compilation error, thereby enforcing immutability. This design is particularly useful for classes that represent immutable data structures or objects where copying or moving would lead to unintended side effects. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Common_NonNullPtr.md b/Romeo/docs/Juliet_include_Core_Common_NonNullPtr.md index a7ae6ea..f0bed45 100644 --- a/Romeo/docs/Juliet_include_Core_Common_NonNullPtr.md +++ b/Romeo/docs/Juliet_include_Core_Common_NonNullPtr.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\Common\NonNullPtr.h` ## AI Description -The Juliet::NonNullPtr class ensures non-null pointers at runtime, initializing and assigning only valid addresses to prevent null pointer errors. It enforces these rules via Asserts in every constructor, assignment operator, accessor, comparison method, and conversion operation while supporting cross-type conversions for compatible types where the base type matches its derived type's internal representation exactly. +The `NonNullPtr` class in the provided C++ component is designed to ensure that a pointer passed to it is never null. It provides a safe way to handle pointers without having to explicitly check for null values, thus reducing potential runtime errors and improving code safety. The class template `NonNullPtr` includes constructors, assignment operators, accessors, and comparison methods to manage the internal pointer safely. Additionally, it prevents assigning a nullptr at compile time by using static assertions in its constructor and assignment operator. This ensures that the pointer is always valid before any operations are performed on it. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Common_Singleton.md b/Romeo/docs/Juliet_include_Core_Common_Singleton.md index 5759f1b..9499c3f 100644 --- a/Romeo/docs/Juliet_include_Core_Common_Singleton.md +++ b/Romeo/docs/Juliet_include_Core_Common_Singleton.md @@ -4,7 +4,17 @@ - Header: `Juliet\include\Core\Common\Singleton.h` ## AI Description -The Juliet::Singleton header enables non-copyable, single-object instances via static registration or auto-registration. It provides a template class with methods to register/unregister and retrieve an instance, ensuring type safety through pointer assertions during the lifecycle management of singleton objects across applications. +The `Singleton.h` header file defines a C++ class template named `Singleton` that provides a global instance of a type, ensuring that only one instance exists throughout the program. The class is designed to be used in two ways: + +1. **Inheritance**: By inheriting from `Singleton::AutoRegister`, you can automatically register your class with the singleton system when it is instantiated. + +2. **Static Methods**: You can use the static methods `Register` and `Unregister` to manually control the registration of your class instance. + +The `Singleton` class uses the `NonMovable` and `NonCopyable` classes from the `Core/Common` namespace to prevent instances from being copied or moved, ensuring that only one instance is created. The `AutoRegister` class is a helper class that automatically registers itself with the singleton system when it is instantiated. + +The `Register` method checks if an instance already exists and asserts that it does not, preventing multiple registrations. Similarly, the `Unregister` method checks if the instance being unregistered matches the currently registered instance and asserts that they match, preventing incorrect unregistrations. + +The `Get` method returns a pointer to the singleton instance, which can be used to access the singleton's methods and properties. The `AutoRegister` class ensures that the singleton instance is properly managed throughout the program, preventing memory leaks or other issues related to singleton usage. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Common_String.md b/Romeo/docs/Juliet_include_Core_Common_String.md index 14adf52..f5826d8 100644 --- a/Romeo/docs/Juliet_include_Core_Common_String.md +++ b/Romeo/docs/Juliet_include_Core_Common_String.md @@ -5,67 +5,75 @@ - Source: `Juliet\src\Core\Common\String.cpp` ## AI Description -Based on the code snippet provided, here is an analysis of the function `ConvertString`, focusing on its logic for handling Unicode decoding (UTF-8), encoding back to UTF-16, and error handling. +The provided code snippet is a part of a library for string manipulation and encoding in C++. It includes functions to convert strings between different encodings, such as UTF-8, ASCII, Latin1, and others. The `ConvertString` function takes two strings (from and to) and converts the from string into the to string format. It supports various encodings including UTF-8, ASCII, Latin1, and others. -### 1. Function Overview -The primary purpose of this class/function block (likely part of a library called "Juliet") is to perform **string conversion** between different character encodings. Specifically: -* It accepts various input formats (`String from`, `String src`). -* It supports specific output formats like UTF-16, ASCII, Latin1, etc., via the helper function. -* The core logic handles converting a source string (currently demonstrated decoding **UTF-8** to code points) and re-encoding it into another format (demonstrated as **UTF-16**), including null termination if requested. +Here's a breakdown of the key components: -### 2. Core Logic: UTF-8 Decoding (`from == StringEncoding::UTF8`) -The decoder implements the RFC 3629 specification for valid Unicode characters in the Basic Multilingual Plane (BMP) and beyond, with specific strictness checks. +### Function Definitions -#### A. Byte Sequence Detection ? Validation -It inspects the first byte of a character sequence to determine its length: -* **4-byte sequence (`0xF0` - `0xFFF`)**: Checks if it matches the standard UTF-8 continuation mask patterns and handles overlong encodings (e.g., using 3 bytes for C2E9 instead of one byte). - * If a leading byte does not match its expected range or has incorrect continuation bits, it marks `character = kUnknown_UNICODE`. -* **3-byte sequence (`0xE0` - `0xFF`)**: Similar checks apply. -* **2-byte sequence (`0xC0` - `0xDF`)**: Checks for the overlong encoding of U+80 (e.g., 0xC1 followed by a continuation byte). -* **1-byte sequence (`0x00` - `0x7F`)**: Ensures high-bit is not set if it's meant to be part of a multi-byte sequence, though the logic here sets `kUnknown_UNICODE` only if `(p[0] ? 0x80)` is true (which covers bytes intended as continuations). +1. **CaseFoldUnicode**: This function is used to fold Unicode characters according to a specific case folding rule. For simplicity, it only supports low ASCII characters (0-127). -#### B. Continuation Byte Processing -After identifying the leading byte: -1. It checks if there are enough remaining bytes in the source (`src.Size`). If not, it logs an error and returns `false`. -2. It iterates through `left` continuation bytes (bits `[6..5] == 0x80`, i.e., values `C0-DF`, `E0-FF`). -3. **Crucial Check**: If a byte is found that does *not* match the UTF-8 continuation pattern (`(p[0] ? 0xC0) != 0x80`), it invalidates the sequence immediately (`kUnknown_UNICODE`). + ```cpp + int CaseFoldUnicode(const char* str, uint32* folded); + ``` -#### C. Surrogate and Invalid Code Point Checks -After reconstructing the `uint32 character`: -1. **Overlong Encoding**: If flags are set, the code resets to unknown. -2. **Control/Invalid Ranges**: Rejects characters in ranges: - * `\uD800` through `\uDFFF` (Surrogate pairs). These cannot exist as standalone characters; they must be paired. Without a following pair context here, it marks them invalid. - * `\xFFFE` and `\xFFFF` (Non-character code points used for replacement markers in internal formats like UTF-16 BE/LE often need special handling or removal from text data). - * Any character ? `0x10FFFF`. +2. **ConvertString**: This function converts a string from one encoding to another. It first determines the source and destination encodings based on the provided strings. -### 3. Encoding Logic: Converting to UTF-16 (`to == StringEncoding::UTF16`) -Once the source is successfully decoded into a single code point (assuming it fits in BMP due to previous checks or surrogates are ignored/handled differently not shown fully here): -* **BMP Characters (? 0x10000)**: Written as two bytes little-endian. - * `p[0] = character ? 0xFF` (Low byte) - * `p[1] = (character ?? 8)` (High byte) -* **Supplemental Characters (? 0x10FFFF)**: Although the decoder rejects input ? 0x10FFF, if logic allows conversion of valid UTF-32 chars here via surrogate pairs: - * Calculates `word1` and `word2`. - * Writes them as two separate UTF-16 code units (4 bytes total). + ```cpp + bool ConvertString(StringEncoding from, StringEncoding to, String src, StringBuffer? dst, bool nullTerminate); + ``` -### 4. Error Handling ? Constraints -The function is designed to be **safe** but strictly validated: -* **Buffer Overflow Protection**: It tracks `remainingCapacity` on the destination buffer before writing each character or block of bytes. If there isn't enough space, it logs an error and fails instead of truncating data. -* **Source Integrity**: Fails fast if the input UTF-8 sequence is incomplete or malformed (broken continuations). -* **Logging**: Uses `Log(LogLevel::Error)` for critical failures like "Incomplete input sequence" or buffer underflow, aiding in debugging during development (`JULIET_DEBUG_ONLY` flags appear to be used elsewhere but not active by default unless defined). +3. **ConvertString**: This is an overloaded version of `ConvertString` that takes a `String` object instead of a `const char*`. -### 5. Wrapper Logic: `ConvertString(String from, String to...)` -The public API calls an inner function after determining formats via `Encodings`: -1. It searches a global or local map (`Encodings`) to find the specific format enum based on string content (case-insensitive compare). -2. If either source or destination is unknown/unfindable, it returns `false`. -3. Delegates to the core decoding/encoding logic with the resolved enums. + ```cpp + bool ConvertString(String from, String to, String src, StringBuffer? dst, bool nullTerminate); + ``` -### Potential Issues / Observations in this Implementation -1. **Surrogate Handling**: The decoder explicitly rejects `\uD800`-\`\uDFFF`. This implies this function is likely intended for converting strings containing *actual* text (no raw surrogates) into UTF-16, or it assumes the caller will handle surrogate pairs before calling this specific helper without a second pass. If input contains valid Unicode characters outside BMP that are being handled via surrogate pairs in the output logic but not checked correctly in input, there might be silent failures depending on how `kUnknown_UNICODE` is propagated later (e.g., ignored vs logged). -2. **Debug Builds**: The line `JULIET_DEBUG_ONLY(...)` suggests this codebase uses debug builds to push data beyond strict alignments or sizes; production logic should ensure alignment safety (`alignof(char)` usually isn't an issue on standard architectures unless specifically targeting edge cases, but it's good practice here). -3. **UTF-16 Direction**: The code assumes Little Endian (writing `p[0]` first as low byte) based on the assignment order `(character ? 0xFF)` then shifting right. This is typical for Windows/WideChar environments which usually use UTF-16LE. +4. **StringCopy**: This function creates a new string in the provided arena with the same content as the input string. -### Summary -This implementation is a **highly defensive string converter** focusing on strict RFC-compliant UTF-8 decoding to code points, rejecting invalid and surrogate-only inputs early in the pipeline before attempting re-encoding to ASCII/Latin/UTF-16. It prioritizes data integrity over flexibility (e.g., it won't silently skip bad bytes). + ```cpp + String StringCopy(NonNullPtr?Arena? arena, String str); + ``` + +### Helper Functions + +1. **StepUTF8**: This function is used to step through UTF-8 encoded characters. + + ```cpp + const char* StepUTF8(const char* str, size_t? remainingSize); + ``` + +2. **StringCompareCaseInsensitive**: This function compares two strings in a case-insensitive manner. + + ```cpp + int StringCompareCaseInsensitive(String str1, String str2); + ``` + +### Encodings + +The `Encodings` array contains information about different string encodings supported by the library: + +```cpp +const Encoding Encodings[] = { + { "UTF8", StringEncoding::UTF8 }, + { "Unknown", StringEncoding::Unknown }, + { "ASCII", StringEncoding::ASCII }, + { "LATIN1", StringEncoding::LATIN1 }, + { "UTF16", StringEncoding::UTF16 }, + { "UTF32", StringEncoding::UTF32 }, + { "UCS2", StringEncoding::UCS2 }, + { "UCS4", StringEncoding::UCS4 } +}; +``` + +### Usage Example + +Here's an example of how to use the `ConvertString` function: + +```cpp +NonNullPtr?Arena? arena = ArenaCreate(); +String str1 = "Hello, World!"; +String str2 ## Symbols @@ -82,7 +90,6 @@ This implementation is a **highly defensive string converter** focusing on stric #### Functions & Methods - `\ MemSet(name##_, 0, sizeof(uint32))` -- `result.Size = anonymous::StringLength(str)` - `return anonymous::IsValid(FindChar(str, c))` - `JULIET_API uint32 StepUTF8(String& inStr)` - `JULIET_API String FindString(String strLeft, String strRight)` diff --git a/Romeo/docs/Juliet_include_Core_Container_Vector.md b/Romeo/docs/Juliet_include_Core_Container_Vector.md index b1bd0d7..43c3222 100644 --- a/Romeo/docs/Juliet_include_Core_Container_Vector.md +++ b/Romeo/docs/Juliet_include_Core_Container_Vector.md @@ -5,7 +5,47 @@ - Source: `Juliet\src\Core\Container\Vector.cpp` ## AI Description -A generic container managing contiguous memory via a custom arena for performance. It supports efficient bulk operations, dynamic resizing, and fast removal by swapping with the end element, designed as a lightweight POD-like object with optional reallocation logic. +The `VectorArena` class in the Juliet library is designed to manage a dynamic array of elements within an arena, which is a memory pool that allocates contiguous blocks of memory. This approach helps in reducing fragmentation and improving performance by minimizing the overhead associated with allocating and deallocating individual memory blocks. + +**Main Purpose:** +- **Memory Management:** The `VectorArena` class provides a flexible way to manage arrays of elements without worrying about memory allocation and deallocation, which can be time-consuming and resource-intensive. +- **Efficiency:** By using an arena, the `VectorArena` minimizes the overhead associated with each memory allocation and deallocation, resulting in faster execution times. +- **Resource Efficiency:** The use of an arena helps in reducing the number of system calls made during memory management operations, which can lead to improved system performance. + +**Design:** +The `VectorArena` class is a template that allows for customization through template parameters such as `Type`, `ReserveSize`, and `AllowRealloc`. It includes methods for creating, destroying, resizing, pushing elements, removing elements, and accessing elements. The class also provides accessors for loop support and index-based access. + +**Key Features:** +- **Arena Management:** The `VectorArena` uses an arena to allocate memory blocks, which helps in reducing fragmentation. +- **Dynamic Resizing:** The `Reserve` method allows for dynamic resizing of the array, ensuring that it can handle varying amounts of data efficiently. +- **Fast Removal:** The `RemoveAtFast` method provides a fast way to remove elements from the array without shifting elements, which is particularly useful in scenarios where performance is critical. + +**Usage:** +To use the `VectorArena`, you can include the header file and create an instance of the class. For example: +```cpp +#include "Juliet/Core/Container/Vector.h" + +int main() +{ + Juliet::Vector?int? vec; + vec.Create(); + + for (int i = 0; i ? 10; ++i) + { + vec.PushBack(i); + } + + // Access elements using index-based access + int firstElement = vec[0]; + + // Remove an element from the array + vec.RemoveAtFast(2); + + return 0; +} +``` + +This example demonstrates how to create a `VectorArena`, push elements onto it, and remove an element. The use of the arena ensures that memory management is efficient and resource-friendly. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_HAL_Display_Display.md b/Romeo/docs/Juliet_include_Core_HAL_Display_Display.md index d8b5a03..47c7b1a 100644 --- a/Romeo/docs/Juliet_include_Core_HAL_Display_Display.md +++ b/Romeo/docs/Juliet_include_Core_HAL_Display_Display.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\HAL\Display\Display.cpp` ## AI Description -This C++ component manages platform-specific windows by initializing a display system via available factories and providing APIs to create, hide, show, destroy, configure titles, and retrieve window identifiers. It encapsulates cross-platform abstraction logic while maintaining state through an internal global device reference for lifecycle management. +The `Display` component in this C++ code is designed to manage and interact with display devices on a platform. It provides functions for creating, destroying, showing, hiding, and managing windows on the display. The component uses an arena-based memory allocator to allocate and deallocate resources efficiently. The `DisplayDeviceFactory` pattern is used to create different types of display devices such as Win32-specific displays. The `InitializeDisplaySystem` function initializes the display system by creating a suitable display device, while the `ShutdownDisplaySystem` function cleans up all resources when the application exits. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_HAL_DynLib_DynamicLibrary.md b/Romeo/docs/Juliet_include_Core_HAL_DynLib_DynamicLibrary.md index 2a09caf..8d984a7 100644 --- a/Romeo/docs/Juliet_include_Core_HAL_DynLib_DynamicLibrary.md +++ b/Romeo/docs/Juliet_include_Core_HAL_DynLib_DynamicLibrary.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\HAL\DynLib\DynamicLibrary.h` ## AI Description -This header declares the DynamicLibrary struct and functions for loading C++ DLLs via filename, retrieving function pointers by name, or unloading libraries using non-null pointer arguments within the JULIET_API naming convention. +The `DynamicLibrary` class in the Juliet library is designed to provide a high-level interface for loading and managing dynamic libraries (DLLs) in C++. It encapsulates the functionality required to load a DLL, retrieve function pointers from it, and unload the DLL when it's no longer needed. The class uses non-null pointers to ensure that the DLL and its functions are properly managed throughout the application. This design allows for easy integration of various libraries into applications without having to manually manage the loading and unloading process. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_HAL_Event_SystemEvent.md b/Romeo/docs/Juliet_include_Core_HAL_Event_SystemEvent.md index 8fcf052..4396a6a 100644 --- a/Romeo/docs/Juliet_include_Core_HAL_Event_SystemEvent.md +++ b/Romeo/docs/Juliet_include_Core_HAL_Event_SystemEvent.md @@ -5,7 +5,31 @@ - Source: `Juliet\src\Core\HAL\Event\SystemEvent.cpp` ## AI Description -The SystemEvent HAL component provides a centralized, timestamped event queue for managing interactions with hardware subsystems like the display, keyboard, and mouse. It defines specific event types (application exit, window close, key/mouse states) using tagged unions to ensure memory efficiency while supporting optional custom data extensions via padding fields. +The `SystemEvent` class in the Juliet library is designed to handle all events from systems responsible for hardware interactions, such as the display and keyboard/mouse. It provides a unified interface for retrieving and managing system events efficiently. + +### Main Purpose: +- **Unifies Event Handling**: The class consolidates various types of system events into a single `SystemEvent` structure, making it easier to manage and process all events in a consistent manner. +- **Efficient Event Queue Management**: The use of a queue allows for efficient retrieval and processing of events without blocking the main thread. This is particularly useful in real-time applications where timely event handling is crucial. + +### Design: +1. **Event Types**: + - `EventType`: A simple enumeration that defines different types of system events, such as application exit, window close request, key down/up, mouse move/button press/release. + - `WindowEvent`, `KeyboardEvent`, `MouseMovementEvent`, and `MouseButtonEvent`: Structs that encapsulate specific details about each type of event, including the associated window ID, keyboard/mouse ID, key state, button state, etc. + +2. **Union for All System Events**: + - `AllSystemEventUnion`: A tagged union that can hold any of the above event types along with additional data if needed. This ensures that all events are handled uniformly and efficiently. + - `Padding`: An array of bytes to make sure the union is fixed in size and big enough on all platforms. + +3. **Event Queue**: + - `eventQueue`: A static queue that stores system events. The queue is used to retrieve events from the main thread without blocking, allowing for efficient event handling in real-time applications. + - `PumpEvents()`: A helper function that updates all systems' event loops and gathers events into the main queue. + +4. **Event Retrieval Functions**: + - `GetEvent(SystemEvent? event)`: Retrieves an event from the queue if available, otherwise returns false. + - `WaitEvent(SystemEvent? event, int32 timeoutInNS = -1)`: Waits for an event to be available in the queue within a specified time period. If no event is available, it returns false. + +### Usage: +To use the `SystemEvent` class, you can simply include the header file and call the appropriate functions to retrieve or wait for events. This ensures that all system events are handled consistently and efficiently, making it easier to manage and respond to hardware interactions in your applications. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_HAL_Filesystem_Filesystem.md b/Romeo/docs/Juliet_include_Core_HAL_Filesystem_Filesystem.md index 71b2be2..2fc5cc9 100644 --- a/Romeo/docs/Juliet_include_Core_HAL_Filesystem_Filesystem.md +++ b/Romeo/docs/Juliet_include_Core_HAL_Filesystem_Filesystem.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\HAL\Filesystem\Filesystem.cpp` ## AI Description -The C++ Filesystem HAL provides application-specific path utilities, caching resolved base directories for compiled assets with platform detection during initialization and managing shared state across the lifecycle. It exposes API functions to retrieve or construct full paths while ensuring memory safety through manual buffer ownership patterns and validation checks on input validity before returning results. +The `Filesystem` component in the Juliet library is designed to manage file paths and operations within a game engine. It provides functions to retrieve the base path of the application directory, the resolved base path for compiled shaders, and build full paths to asset files based on their filenames. The component also includes functionality to check if a given path is absolute and initializes the filesystem by probing candidate paths for the compiled shader directory. This ensures that the engine can locate necessary resources correctly during runtime. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_HAL_IO_IOStream.md b/Romeo/docs/Juliet_include_Core_HAL_IO_IOStream.md index 92ee676..da2fed9 100644 --- a/Romeo/docs/Juliet_include_Core_HAL_IO_IOStream.md +++ b/Romeo/docs/Juliet_include_Core_HAL_IO_IOStream.md @@ -5,7 +5,17 @@ - Source: `Juliet\src\Core\HAL\IO\IOStream.cpp` ## AI Description -The IOStream component provides a unified, opaque interface for reading and writing data to diverse sources like files or memory. Its design abstracts platform-specific details through pointer function interfaces while exposing high-level functions (e.g., IOPrintf) that handle edge cases such as file loading with dynamic resizing and error status reporting. +The `IOStream` component in the Juliet library is designed to provide a unified interface for reading and writing data from various sources, such as files or memory buffers. It supports both file-based and memory-based operations, allowing developers to interact with different types of data sources in a consistent manner. + +The `IOStream` class encapsulates the functionality required to manage the stream's state, including its status (ready, error, end of file), position within the stream, and the ability to read from or write to the stream. It also provides methods for seeking within the stream and determining its size. + +The `IOFromFile` function allows developers to open a file by providing the filename and mode as parameters. The `IOFromInterface` function enables developers to use an existing interface to open any I/O stream, which can be particularly useful when integrating with external libraries or frameworks that provide custom I/O interfaces. + +The `IOPrintf`, `IOWrite`, `IORead`, `IOSeek`, and `IOSize` functions are used to perform various operations on the I/O stream. These functions handle file reading and writing, as well as seeking within the stream, and return the number of bytes read or written. + +The `LoadFile` function is a utility function that loads data from a file into a ByteBuffer. It uses the `IOFromFile` function to open the file and then reads its contents into a buffer. The `LoadFile` function also provides an option to close the stream after loading the data, which can be useful for freeing up resources. + +The `IOClose` function is used to close the I/O stream and free any associated resources. It ensures that the stream is properly closed before it is deleted, preventing memory leaks or other issues. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_HAL_Keyboard_KeyCode.md b/Romeo/docs/Juliet_include_Core_HAL_Keyboard_KeyCode.md index 51af15f..ae29a7e 100644 --- a/Romeo/docs/Juliet_include_Core_HAL_Keyboard_KeyCode.md +++ b/Romeo/docs/Juliet_include_Core_HAL_Keyboard_KeyCode.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\HAL\Keyboard\KeyCode.h` ## AI Description -The `KeyCode.h` component defines localized virtual keys mapping physical scans to platform-independent ASCII values and special control codes. It uses unique enumeration entries for character generation plus non-character events, while providing a complementary bitwise flag set in the adjacent `KeyMod` enum for modifier states. +The `KeyCode` enum in the provided C++ header file represents a virtual key corresponding to a physical key, localized using the keyboard layout. It includes both ASCII and non-ASCII characters, with some keys mapped to specific scan codes for different keyboards (e.g., WASD keys on French keyboards). The `KeyMod` enum is used to represent modifier keys such as Shift, Control, Alt, and OSCommand, which can be combined using bitwise operations. This component is designed to facilitate input handling in applications that require keyboard input management. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_HAL_Keyboard_Keyboard.md b/Romeo/docs/Juliet_include_Core_HAL_Keyboard_Keyboard.md index 6213f31..4f105c3 100644 --- a/Romeo/docs/Juliet_include_Core_HAL_Keyboard_Keyboard.md +++ b/Romeo/docs/Juliet_include_Core_HAL_Keyboard_Keyboard.md @@ -4,7 +4,11 @@ - Header: `Juliet\include\Core\HAL\Keyboard\Keyboard.h` ## AI Description -This header defines core C++ classes and functions for keyboard hardware interaction. It provides data structures like `Key` to store input details and utility APIs such as `IsKeyDown`, allowing applications to query the current state of physical keys within the Juliet system framework. +The `Keyboard.h` header file in the Juliet project is designed to provide a robust interface for handling keyboard input. It includes the necessary headers and defines structures to represent keys on the keyboard, such as their scan codes, key codes, and raw values. + +The main purpose of this component is to facilitate easy access to keyboard state information within the Juliet framework. The `IsKeyDown` function allows developers to check if a specific key is currently pressed, while `GetKeyModState` provides the current state of modifier keys like Shift, Ctrl, and Alt. The `GetKeyCodeFromScanCode` function maps a scan code to its corresponding key code, which can be useful for applications that require precise control over keyboard input. + +This component is crucial for any application that needs to interact with the user's keyboard, such as text entry, gaming, or automation tasks. By providing a clear and efficient interface, it enables developers to focus on the core functionality of their application without worrying about low-level keyboard interactions. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_HAL_Keyboard_ScanCode.md b/Romeo/docs/Juliet_include_Core_HAL_Keyboard_ScanCode.md index d84286b..d505544 100644 --- a/Romeo/docs/Juliet_include_Core_HAL_Keyboard_ScanCode.md +++ b/Romeo/docs/Juliet_include_Core_HAL_Keyboard_ScanCode.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\HAL\Keyboard\ScanCode.h` ## AI Description -This header defines a `uint16` ScanCode enumeration mapping physical keyboard keys to USB HID Usage IDs per the HUT specification. It covers alphanumeric characters, function keys, navigation buttons, media controls, and modifier keys while accounting for layout variations like ISO/ANSI keyboards. The design adheres strictly to the Hardware User Tracking Protocol standard, ensuring accurate hardware-level key identification across platforms including PC and Mac variants through reserved values up to 512. +The `ScanCode` enum in the `Juliet::HAL::Keyboard` header file is designed to represent physical keys and buttons on a keyboard. It follows the HID Usage page for USB, which categorizes these codes into two main groups: Keyboard Usage Page (0x07) and Consumer Usage Page (0xC). The enum includes a range of predefined key codes, such as letters, numbers, special characters, arrow keys, and function keys. Additionally, it provides constants for power management and media controls. This enumeration is crucial for applications that need to interact with keyboards in a standardized way across different platforms. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_HAL_Mouse_Mouse.md b/Romeo/docs/Juliet_include_Core_HAL_Mouse_Mouse.md index f2b1df9..a7651e9 100644 --- a/Romeo/docs/Juliet_include_Core_HAL_Mouse_Mouse.md +++ b/Romeo/docs/Juliet_include_Core_HAL_Mouse_Mouse.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\HAL\Mouse\Mouse.h` ## AI Description -The C++ `Juliet` component provides a low-level abstraction for mouse input via HAL, defining enums and structs to represent buttons (left/right/middle) and 2D coordinates. It exports external functions in the `MouseInput()` category to check button states, retrieve position data, and manage hardware interactions efficiently within the Juliet framework's core architecture. +The `Mouse.h` header file in the Juliet project defines a C++ component for handling mouse input. It includes the necessary namespaces and enumerations to represent different mouse buttons and their states. The `MousePosition` struct is used to store the current position of the mouse cursor on the screen. The functions `IsMouseButtonDown`, `GetMousePosition`, and `GetMouseButtonState` are provided to interact with the mouse, allowing developers to check if a specific button is pressed or retrieve its current state. This component is essential for applications that require precise control over user input, such as games or interactive interfaces. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_HAL_OS_OS.md b/Romeo/docs/Juliet_include_Core_HAL_OS_OS.md index f2568a7..c912377 100644 --- a/Romeo/docs/Juliet_include_Core_HAL_OS_OS.md +++ b/Romeo/docs/Juliet_include_Core_HAL_OS_OS.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\HAL\OS\OS.cpp` ## AI Description -This header defines the `Juliet` OS abstraction layer for memory management and debugging in a C++ application. It provides functions to reserve, commit (make executable), and release virtual addresses via byte-based interfaces, along with template overloads for typed allocations, as well as utilities like debugger detection and bootstrapping entry points. +This C++ component provides a set of functions for managing memory in the Juliet framework. It includes functions to reserve, commit, and release memory, as well as a function to check if a debugger is present. The `OS` class encapsulates these functionalities within its own namespace, ensuring that they are isolated from other parts of the codebase. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_HotReload_HotReload.md b/Romeo/docs/Juliet_include_Core_HotReload_HotReload.md index d42b945..fdb8e5c 100644 --- a/Romeo/docs/Juliet_include_Core_HotReload_HotReload.md +++ b/Romeo/docs/Juliet_include_Core_HotReload_HotReload.md @@ -5,7 +5,13 @@ - Source: `Juliet\src\Core\HotReload\HotReload.cpp` ## AI Description -HotReload manages dynamic C++ DLL loading/unloading via JSON signals. It stores paths, function addresses in an Arena, and handles incremental updates through atomic file locks with retry logic on failure. +The `HotReload` component in the Juliet library is designed to facilitate hot code reloading for applications. It provides a set of functions to initialize, shutdown, load, and unload code dynamically. The main purpose of this component is to allow developers to modify their application's code without having to restart the entire application, which can be time-consuming and disruptive. + +The `HotReloadCode` struct encapsulates all the necessary information for managing the hot reload process, including paths to the DLLs, lock files, and memory arenas. The `InitHotReloadCode` function initializes these paths based on the base path of the application and creates the required full paths. It also loads the code into an arena. + +The `ShutdownHotReloadCode` function releases all resources associated with the hot reload process, including the arena and any allocated memory. The `ReloadCode` function attempts to load the code again after a specified number of tries, ensuring that the application can continue running without interruption. + +This component is particularly useful for development environments where changes are frequent or when debugging issues in real-time. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_ImGui_ImGuiService.md b/Romeo/docs/Juliet_include_Core_ImGui_ImGuiService.md index 4568a8f..f06f621 100644 --- a/Romeo/docs/Juliet_include_Core_ImGui_ImGuiService.md +++ b/Romeo/docs/Juliet_include_Core_ImGui_ImGuiService.md @@ -5,7 +5,38 @@ - Source: `Juliet\src\Core\ImGui\ImGuiService.cpp` ## AI Description -The ImGuiService component initializes, renders, and manages the ImGui framework within the Juliet application. Its main responsibility is to bridge high-level UI logic with low-level graphics hardware via a dedicated memory arena and custom allocators, ensuring efficient resource usage while supporting keyboard navigation on Windows platforms when enabled at compile time. +The `ImGuIService` class in the Juliet project is designed to integrate and manage the functionality of the ImGui library within a game engine. This component provides a high-level interface for rendering user interfaces (UI) directly on the graphics device, allowing developers to create interactive applications with minimal overhead. + +### Main Purpose: +- **Integration**: The `ImGuIService` class facilitates the integration of ImGui into the Juliet project, enabling developers to use ImGui's UI components within their game logic. +- **Performance**: By using a dedicated Paged Arena for ImGui, the service ensures efficient memory management and reduces the overhead associated with creating and destroying ImGui elements. +- **Platform Compatibility**: The implementation supports Windows-specific features through the `Win32Window` class, ensuring compatibility across different platforms. + +### Design: +1. **Initialization**: + - Initializes the ImGui context using an Engine Pool for memory allocation. + - Sets up allocator functions to manage memory allocations and deallocations. + - Configures ImGui with keyboard controls enabled. + +2. **Shutdown**: + - Cleans up resources by shutting down ImGui, destroying the context, and releasing the arena. + +3. **New Frame**: + - Prepares the environment for a new frame by calling `ImGui_ImplWin32_NewFrame` and `ImGui::NewFrame`. + +4. **Render**: + - Renders the UI elements using `ImGui::Render`. + +5. **Initialization Check**: + - Checks if the service is initialized before performing any operations. + +6. **Context Access**: + - Provides a method to access the current ImGui context for advanced customization or debugging purposes. + +7. **Unit Tests**: + - Contains a function to run internal unit tests, ensuring the service functions as expected. + +This component is crucial for creating interactive user interfaces in games, enhancing the user experience by providing a flexible and powerful UI framework. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_ImGui_ImGuiTests.md b/Romeo/docs/Juliet_include_Core_ImGui_ImGuiTests.md index 4e71b34..2d00606 100644 --- a/Romeo/docs/Juliet_include_Core_ImGui_ImGuiTests.md +++ b/Romeo/docs/Juliet_include_Core_ImGui_ImGuiTests.md @@ -5,7 +5,11 @@ - Source: `Juliet\src\Core\ImGui\ImGuiTests.cpp` ## AI Description -This unit test verifies the initialization and correctness of the ImGui integration within Juliet. It confirms context alignment, validates backend status, checks font atlas generation, and ensures core rendering components are properly configured before drawing begins. +The `ImGuiTests.h` header file defines a C++ class named `Juliet::UnitTest::TestImGui` that serves as a test suite for the ImGui library within the Juliet framework. The primary purpose of this component is to verify the correctness and functionality of the ImGui rendering engine, ensuring compatibility with the Juliet graphics system. + +The source file `ImGuiTests.cpp` contains the implementation of the `TestImGui` function, which performs several checks to validate the various aspects of the ImGui context, fonts, style, and drawing list functionalities. The test suite includes assertions to ensure that the ImGui context is properly set up, that the font atlas is built correctly, and that the ImGui rendering engine functions as expected. + +The tests cover essential components such as the backend platform name, version, fonts, style, and draw list access. By running this test suite, developers can confirm that the ImGui library is integrated seamlessly with the Juliet framework and meets the required standards for rendering graphics in a user interface. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_JulietInit.md b/Romeo/docs/Juliet_include_Core_JulietInit.md index 40136e5..b6a6f4a 100644 --- a/Romeo/docs/Juliet_include_Core_JulietInit.md +++ b/Romeo/docs/Juliet_include_Core_JulietInit.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\JulietInit.h` ## AI Description -The `JulietInit.h` header defines core initialization for the Juliet framework via a bit-flag enum and arena management parameters. It exposes public functions to initialize, configure game states, and cleanly shut down system components within the provided namespaces. This component serves as an essential bootstrap layer for setting up runtime environments like display and audio subsystems before application logic executes. +This C++ component, `JulietInit`, is designed to initialize the core functionalities of a game engine. It includes settings for enabling various subsystems such as display and audio, along with an enumeration to manage different initialization flags. The `GameInitParams` structure holds pointers to arenas used by the game engine, which are essential for managing memory allocations during runtime. The `JulietInit` function initializes these subsystems based on the provided flags, while `JulietShutdown` is responsible for cleaning up resources when the game engine is shut down. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Logging_LogManager.md b/Romeo/docs/Juliet_include_Core_Logging_LogManager.md index 4bdcfba..50c367c 100644 --- a/Romeo/docs/Juliet_include_Core_Logging_LogManager.md +++ b/Romeo/docs/Juliet_include_Core_Logging_LogManager.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\Logging\LogManager.cpp` ## AI Description -The C++ LogManager provides centralized logging via `LogScope`, an arena-based system for memory management. It uses a circular buffer to accumulate log entries per frame and supports Windows debug output with platform-specific formatting, while deferring file export until the end of a scope. Initialization requires manual setup; shutdown cleans up resources using custom allocators. +The `LogManager` component in the Juliet library is designed to manage and output log messages. It provides a flexible framework for logging at different levels (Debug, Message, Warning, Error) with categories to categorize logs based on their importance. The component uses an arena-based memory management system to efficiently allocate and deallocate memory for log entries. Logs are accumulated in scopes until the scope is ended, which then writes them to a file or other output destination. The `LogManager` also includes functions to initialize and shutdown the logging system, as well as to log messages with specific levels and categories. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Logging_LogTypes.md b/Romeo/docs/Juliet_include_Core_Logging_LogTypes.md index a0b85d0..b31f025 100644 --- a/Romeo/docs/Juliet_include_Core_Logging_LogTypes.md +++ b/Romeo/docs/Juliet_include_Core_Logging_LogTypes.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\Logging\LogTypes.h` ## AI Description -This header defines log levels and categories for the Juliet C++ project. It uses fixed-size integers (uint8) to represent Debug, Warning, Error states and Core through Game subsystems, establishing a structured type system for logging operations across the application architecture without dynamic storage overhead. The design ensures efficiency by limiting values to eight bits while supporting six distinct operational channels essential for debugging and system monitoring within Juliet's core framework. +This C++ component defines two enumerations, `LogLevel` and `LogCategory`, which are used to categorize log messages in a game development context. The `LogLevel` enum represents different severity levels of logs (Debug, Message, Warning, Error), while the `LogCategory` enum specifies the type of log message (Core, Graphics, Networking, Engine, Tool, Game). This design allows for flexible logging that can be easily adjusted based on the needs of different parts of a game. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Main.md b/Romeo/docs/Juliet_include_Core_Main.md index a857ef3..8c183a1 100644 --- a/Romeo/docs/Juliet_include_Core_Main.md +++ b/Romeo/docs/Juliet_include_Core_Main.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\Main.h` ## AI Description -This component defines the C++ application entry point for Windows platforms. It encapsulates platform-specific logic in `main`, `wWinMain`, and a global function symbol, utilizing variadic arguments to bootstrap core initialization via Juliet::Bootstrap before executing main logic. +This C++ component provides a unified entry point for the application, handling both Windows and non-Windows platforms. It includes a `JulietMain` function that serves as the entry point for the application, which is called by the operating system. The main function is designed to be compatible with both Unicode and ANSI environments, using `wmain` on Windows and `main` on Unix-like systems. The component also provides a C-style interface through the `extern "C"` block, allowing other libraries or applications to call the `JulietMain` function directly. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Math_MathUtils.md b/Romeo/docs/Juliet_include_Core_Math_MathUtils.md index f1cfa34..434227d 100644 --- a/Romeo/docs/Juliet_include_Core_Math_MathUtils.md +++ b/Romeo/docs/Juliet_include_Core_Math_MathUtils.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\Math\MathUtils.h` ## AI Description -This component provides fundamental mathematical utilities including rounding, integer conversion, and template-based min/max functions. It implements clamping logic for both fixed values and range limits via generic templates designed to constrain numeric types within specified bounds while maintaining constexpr evaluation capabilities during compilation phases in the Juliet framework architecture system where performance optimization remains a core design principle throughout all project layers enabling seamless integration into complex mathematical calculations across game development scenarios without requiring runtime overhead or sacrificing code maintainability. +The `MathUtils.h` header file in the Juliet project is designed to provide a collection of utility functions for mathematical operations. It includes functions such as rounding, clamping, and finding the minimum and maximum values among two numbers. These utilities are essential for various computational tasks within the Juliet framework, ensuring that numerical computations are handled correctly and efficiently. The `MathUtils` class encapsulates these functionalities in a namespace to maintain code organization and avoid naming conflicts with other parts of the project. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Math_Matrix.md b/Romeo/docs/Juliet_include_Core_Math_Matrix.md index 1cf5ffe..311015d 100644 --- a/Romeo/docs/Juliet_include_Core_Math_Matrix.md +++ b/Romeo/docs/Juliet_include_Core_Math_Matrix.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\Math\Matrix.h` ## AI Description -The Juliet Matrix struct provides a fixed-size float[4][4] representation for linear transformations. It includes factory functions and inline operators to generate Identity, Translation, Scaling, Rotation (axis-angle or Euler), Perspective projection, LookAt camera views, and compute the matrix inverse via cofactor expansion with determinant normalization. +The `Matrix` class in the provided C++ component is designed to represent a 4x4 matrix, which is fundamental for various mathematical operations such as transformations in computer graphics and physics simulations. The class includes methods to create identity matrices, perform matrix multiplication, handle translations, scaling, rotations, and look-at transformations. It also provides an inverse method to compute the multiplicative inverse of a given matrix. This component is essential for handling transformations in 3D space, enabling applications such as game development, physics simulations, and computer graphics rendering. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Math_Shape.md b/Romeo/docs/Juliet_include_Core_Math_Shape.md index c69979b..92145e8 100644 --- a/Romeo/docs/Juliet_include_Core_Math_Shape.md +++ b/Romeo/docs/Juliet_include_Core_Math_Shape.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\Math\Shape.h` ## AI Description -The provided description for the `Rectangle` structure in the Juliet framework's Shape module is accurate and concise, detailing four properties (X position, Y position, width, height) as integer coordinates necessary for defining a 2D geometric shape within their core system. As it stands without any additional context or functionality requirements, no changes are needed to maintain this clear definition of basic rectangular geometry data. +The `Rectangle` structure in the `Juliet::Math` namespace is designed to encapsulate a geometric rectangle with properties such as its top-left corner coordinates (`X`, `Y`) and dimensions (`Width`, `Height`). This structure provides a clear and organized way to represent rectangles, facilitating operations like area calculation, position manipulation, and collision detection within a game or application. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Math_Vector.md b/Romeo/docs/Juliet_include_Core_Math_Vector.md index f63c759..2fcaba5 100644 --- a/Romeo/docs/Juliet_include_Core_Math_Vector.md +++ b/Romeo/docs/Juliet_include_Core_Math_Vector.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\Math\Vector.h` ## AI Description -This component defines lightweight 3D and 4D vector structures in the C++ library, providing fundamental arithmetic operations like addition, subtraction, dot product, normalization, and cross products. Designed for performance, it uses a simple struct layout to enable rapid mathematical calculations within geometry systems without overhead from complex types or methods. +The `Vector.h` header file in the Juliet project defines two classes, `Vector3` and `Vector4`, which are used to represent 3D and 4D vectors respectively. These classes provide basic arithmetic operations such as addition, subtraction, scalar multiplication, normalization, cross product, and dot product. The `Normalize` function calculates the magnitude of a vector and returns a normalized version of it if the magnitude is greater than a small threshold (0.0001f). This utility function simplifies vector manipulation in 3D graphics and physics simulations. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Memory_Allocator.md b/Romeo/docs/Juliet_include_Core_Memory_Allocator.md index 9b79140..8178390 100644 --- a/Romeo/docs/Juliet_include_Core_Memory_Allocator.md +++ b/Romeo/docs/Juliet_include_Core_Memory_Allocator.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\Memory\Allocator.cpp` ## AI Description -The Juliet Allocator provides Malloc, Calloc, and Realloc functions with zero-size safeguards. It includes Free templates for releasing heap data while using internal assertions to ensure successful allocation and prevent out-of-memory failures during runtime. +This C++ component provides a set of functions for managing dynamic memory allocation and deallocation in the Juliet framework. The primary purpose is to ensure that memory is allocated correctly and safely, handling edge cases such as zero-sized allocations. The `Malloc` function allocates uninitialized memory, while `Calloc` initializes it to zero. The `Realloc` function allows resizing existing memory blocks. The component includes a template version of the `Free` function to handle different types of pointers, ensuring that the pointer is set to `nullptr` after deallocation. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Memory_MemoryArena.md b/Romeo/docs/Juliet_include_Core_Memory_MemoryArena.md index 9289061..15976e7 100644 --- a/Romeo/docs/Juliet_include_Core_Memory_MemoryArena.md +++ b/Romeo/docs/Juliet_include_Core_Memory_MemoryArena.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\Memory\MemoryArena.cpp` ## AI Description -Provides zero-copy memory allocation via fixed-size contiguous blocks with dynamic resizing. Designed for high-performance critical sections, it manages reserved/committed pages and a linked-list free list to minimize GC overhead while supporting safe reuse of large allocations. +This C++ component is designed to manage memory allocations and deallocations in a high-performance manner. It provides an efficient way to allocate, reallocate, and free memory blocks within a single arena, which can be particularly useful for optimizing memory usage in applications that require frequent memory management. The component includes features such as automatic memory allocation, reallocation, and deallocation, as well as support for debugging information to help identify memory leaks or other issues. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Memory_MemoryArenaDebug.md b/Romeo/docs/Juliet_include_Core_Memory_MemoryArenaDebug.md index 43f4a9d..c4f770d 100644 --- a/Romeo/docs/Juliet_include_Core_Memory_MemoryArenaDebug.md +++ b/Romeo/docs/Juliet_include_Core_Memory_MemoryArenaDebug.md @@ -5,7 +5,11 @@ - Source: `Juliet\src\Core\Memory\MemoryArenaDebug.cpp` ## AI Description -This debug component tracks memory allocations for all registered arenas, maintaining per-block metadata (size, offset, tags) and a global arena list. It supports registration/unregistration of arenas, dynamic name setting, block deletion, selective allocation removal, range truncation via `PopTo`, and dedicated free-list management to enable leak analysis and heap debugging during development builds only. +The `MemoryArenaDebug.h` header file provides a debug mechanism for managing memory allocations within an arena, allowing developers to track and manage the allocation history of memory blocks. The `MemoryArenaDebug.cpp` source file implements these functionalities, including registering and unregistering arenas, setting debug names, freeing debug information from blocks, removing allocations, popping allocations to a new position, and adding debug information for each allocation. + +The `ArenaDebugInfo` struct is used to store detailed information about each memory block, such as the tag associated with it, its size, offset within the arena, and pointers to the next debug information entry. The `ArenaAllocation` struct represents individual allocations within an arena, including their size, offset, and a reference to the tag. + +The `DebugRegisterArena`, `DebugUnregisterArena`, `DebugArenaSetDebugName`, `IsDebugInfoArena`, `DebugArenaFreeBlock`, `DebugArenaRemoveAllocation`, `DebugArenaPopTo`, and `DebugArenaAddDebugInfo` functions handle various aspects of arena management, ensuring that debug information is correctly tracked and managed throughout the application. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Memory_Utils.md b/Romeo/docs/Juliet_include_Core_Memory_Utils.md index 06d10fe..c06301b 100644 --- a/Romeo/docs/Juliet_include_Core_Memory_Utils.md +++ b/Romeo/docs/Juliet_include_Core_Memory_Utils.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\Memory\Utils.h` ## AI Description -This header provides Julia's memory utility functions and list implementations. It includes helper macros for array sizing and memory operations like memset/memcopy replacements. The module defines single/double linked lists with insertion/pop operations using pointer references, along with generic queue nodes and a custom declaration macro to support advanced data structure management efficiently within the Juliet framework. +The `Utils.h` header file in the Juliet project is designed to provide utility functions and data structures for memory management. It includes functions such as `MemCompare`, which compares two blocks of memory, and a single linked list implementation with push and pop operations. Additionally, it defines a template-based queue structure that can be used to manage a collection of elements. The source file contains implementations for these functions and the queue structure, along with macros for setting up queues and pushing nodes into them. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Networking_IPAddress.md b/Romeo/docs/Juliet_include_Core_Networking_IPAddress.md index ba2fd1b..3c19d17 100644 --- a/Romeo/docs/Juliet_include_Core_Networking_IPAddress.md +++ b/Romeo/docs/Juliet_include_Core_Networking_IPAddress.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\Networking\IPAddress.h` ## AI Description -Defines core IPv4 addressing utilities in the Juliet networking layer. Provides precomputed constants for localhost, any address, and broadcast IPs using bitwise operations to facilitate network communication initialization and validation within the application architecture. +The `IPAddress.h` header file in the Juliet project is designed to provide a simple and efficient way to handle IP addresses in C++. It includes constants for common IP addresses such as localhost, any IP address, and broadcast IP address. The class encapsulates these values using a 32-bit unsigned integer, which allows for easy manipulation and comparison of IP addresses. The use of constexpr ensures that the values are defined at compile time, making them suitable for use in constant expressions and template parameters. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Networking_NetworkPacket.md b/Romeo/docs/Juliet_include_Core_Networking_NetworkPacket.md index bc8fc69..b72cb1f 100644 --- a/Romeo/docs/Juliet_include_Core_Networking_NetworkPacket.md +++ b/Romeo/docs/Juliet_include_Core_Networking_NetworkPacket.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\Networking\NetworkPacket.cpp` ## AI Description -The `NetworkPacket` class encapsulates network transmission logic by storing raw binary data in a vector and supporting serialization operations like converting integers to host order. It manages partial sends via an index, exposes unmarshaling methods for structured parsing, allows retrieving full packet contents as byte buffers, implements move semantics without throwing exceptions, uses friend access from sockets directly, avoids copying large blocks of memory by design, ensures thread safety through atomic updates on shared state variables when needed internally across multiple execution contexts. +The `NetworkPacket` class in the Juliet library is designed to handle network data packets efficiently. It uses a `Vector?Byte?` to store the raw bytes of the packet, which allows for dynamic resizing and efficient memory management. The class provides methods to serialize and deserialize various types of data into the packet, such as integers and strings. The `GetRawData` method returns the entire packet as a `ByteBuffer`, which can be used for transmission over a network or saved to a file. The class also includes friend functions for easy serialization and deserialization of specific data types. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Networking_Socket.md b/Romeo/docs/Juliet_include_Core_Networking_Socket.md index 7436fd9..9e84dcd 100644 --- a/Romeo/docs/Juliet_include_Core_Networking_Socket.md +++ b/Romeo/docs/Juliet_include_Core_Networking_Socket.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\Networking\Socket.cpp` ## AI Description -The Juliet Socket class provides a unified, non-copyable interface for TCP and UDP communication using Windows sockets. It manages socket lifecycle via validation, creation with optional flow control (TCP_NODELAY), and cleanup through the underlying platform implementation while enforcing protocol-specific logic boundaries. +The `Socket` class in the Juliet project is designed to manage network connections, providing a high-level interface for sending and receiving data over TCP or UDP protocols. It encapsulates socket operations such as creation, handling of socket errors, and managing the underlying socket handle. The class ensures that sockets are properly closed when they are no longer needed, preventing resource leaks. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Networking_SocketHandle.md b/Romeo/docs/Juliet_include_Core_Networking_SocketHandle.md index 358da28..057a027 100644 --- a/Romeo/docs/Juliet_include_Core_Networking_SocketHandle.md +++ b/Romeo/docs/Juliet_include_Core_Networking_SocketHandle.md @@ -4,7 +4,13 @@ - Header: `Juliet\include\Core\Networking\SocketHandle.h` ## AI Description -SocketHandle defines a cross-platform socket identifier type, mapping to platform-specific primitives like Win32's UINT_PTR or POSIX-compatible integers, ensuring unified resource tracking across operating systems within the Juliet networking subsystem. +The `SocketHandle` class in the Juliet library is designed to represent a handle for network sockets. It encapsulates the underlying socket descriptor, which is used by the operating system to manage network connections. The class provides a unified interface for interacting with different types of sockets across various platforms, ensuring compatibility and abstraction. + +The design decision to use `UINT_PTR` on Windows and `int` on non-Windows systems allows for flexibility in handling different sizes of socket descriptors, which can be crucial depending on the specific requirements of the application. This approach ensures that the class is portable and can be used across different operating systems without significant modifications. + +The class provides methods for creating sockets, connecting to remote servers, sending and receiving data over the network, and managing socket events. It also includes error handling mechanisms to manage potential issues such as connection failures or network errors. + +Overall, the `SocketHandle` class serves as a robust foundation for network programming in Juliet, providing a clean and efficient interface for interacting with sockets across different platforms. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Networking_TcpListener.md b/Romeo/docs/Juliet_include_Core_Networking_TcpListener.md index ccf4855..6f3c3a5 100644 --- a/Romeo/docs/Juliet_include_Core_Networking_TcpListener.md +++ b/Romeo/docs/Juliet_include_Core_Networking_TcpListener.md @@ -5,7 +5,11 @@ - Source: `Juliet\src\Core\Networking\TcpListener.cpp` ## AI Description -The `TcpListener` component facilitates TCP network connections within the Juliet framework. It encapsulates socket operations to bind and listen on specific local ports while accepting incoming client requests, returning new sockets for further communication or reusing its internal handle for dynamic port changes when configured accordingly. +The `TcpListener` class in the Juliet library is designed to facilitate TCP server functionality. It encapsulates the necessary components for creating, listening on, and accepting connections over a network. The class inherits from the `Socket` class, which provides common socket functionalities such as creation, binding, listening, and closing sockets. + +The main purpose of this component is to allow developers to easily set up and manage TCP servers in their applications. It supports both IPv4 and IPv6 addresses, allowing for flexibility in network communication. The `Listen` method allows the server to start accepting connections on a specified port and address, while the `Accept` method is used to accept incoming connections and create new `TcpSocket` instances for handling each connection. + +The class also includes error handling mechanisms through logging, which provides feedback on any issues that occur during socket operations. This ensures that developers can quickly identify and resolve problems related to network connectivity. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Networking_TcpSocket.md b/Romeo/docs/Juliet_include_Core_Networking_TcpSocket.md index 645db76..e281934 100644 --- a/Romeo/docs/Juliet_include_Core_Networking_TcpSocket.md +++ b/Romeo/docs/Juliet_include_Core_Networking_TcpSocket.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\Networking\TcpSocket.cpp` ## AI Description -The `TcpSocket` class handles TCP networking, inheriting from `Socket`. It manages data transmission and reception using raw network packets. Its primary responsibilities include constructing a socket instance with the TCP protocol configuration and providing methods for sending and receiving network data via underlying OS primitives. Design features prevent copying to ensure single ownership. +The `TcpSocket` class in the Juliet library is designed to facilitate TCP communication over a network. It inherits from the base `Socket` class and provides methods for sending and receiving data packets. The primary purpose of this component is to handle low-level TCP socket operations, including opening connections, sending data, and receiving responses. The class uses a scratch allocator to manage the buffer used for sending data, ensuring that the packet size is correctly transmitted before actual data is sent. Additionally, it includes error handling mechanisms to manage network issues and partial sends. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Thread_Mutex.md b/Romeo/docs/Juliet_include_Core_Thread_Mutex.md index 7329fff..88429c2 100644 --- a/Romeo/docs/Juliet_include_Core_Thread_Mutex.md +++ b/Romeo/docs/Juliet_include_Core_Thread_Mutex.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Core\Thread\Mutex.h` ## AI Description -Provides a lightweight threading synchronization mechanism by aliasing standard library `std::mutex` and its RAII guard, ensuring thread safety for resource protection without introducing custom logic or overhead. +The `Mutex` class in the Juliet library is designed to provide mutual exclusion for critical sections of code, ensuring that only one thread can execute a piece of code at a time. This is crucial for maintaining data integrity and preventing race conditions in multi-threaded applications. The `LockGuard` class is used to manage the locking and unlocking of the mutex automatically when it goes out of scope, which simplifies the management of locks and reduces the risk of forgetting to unlock them. ## Symbols diff --git a/Romeo/docs/Juliet_include_Core_Thread_Thread.md b/Romeo/docs/Juliet_include_Core_Thread_Thread.md index 06d3b79..11f3b06 100644 --- a/Romeo/docs/Juliet_include_Core_Thread_Thread.md +++ b/Romeo/docs/Juliet_include_Core_Thread_Thread.md @@ -4,7 +4,19 @@ - Header: `Juliet\include\Core\Thread\Thread.h` ## AI Description -Juliet::Thread provides a thin abstraction over std::thread, implementing an inefficient sleep function using the standard library without additional dependencies. +The `Thread.h` header file defines a C++ class named `Thread` that encapsulates the functionality of creating and managing threads. The main purpose of this component is to provide a simple interface for creating, starting, and stopping threads in a multi-threaded environment. + +The design of the `Thread` class includes the following key features: + +1. **Thread Creation**: The `Thread` class provides a constructor that takes a function pointer as an argument and creates a new thread by calling the provided function. + +2. **Thread Execution**: Once a thread is created, it can be started using the `start()` method of the `std::thread` class. This method begins executing the function passed to the constructor in a separate thread. + +3. **Thread Management**: The `Thread` class also includes methods for stopping threads. The `stop()` method allows you to request that a thread stop its execution, and the `join()` method waits for a thread to complete its execution before proceeding. + +4. **Wait Function**: The `wait_ms` function is provided as an inline function within the `Thread.h` header file. It takes an integer parameter representing the number of milliseconds to wait before continuing execution. This function uses the `?chrono?` library to sleep for the specified duration. + +5. **Namespace and Naming Convention**: The `Thread` class is defined in a namespace named `Juliet`, which follows the standard C++ naming convention for namespaces. ## Symbols diff --git a/Romeo/docs/Juliet_include_Engine_Class.md b/Romeo/docs/Juliet_include_Engine_Class.md index d877292..6146aa2 100644 --- a/Romeo/docs/Juliet_include_Engine_Class.md +++ b/Romeo/docs/Juliet_include_Engine_Class.md @@ -4,7 +4,11 @@ - Header: `Juliet\include\Engine\Class.h` ## AI Description -The `Juliet::Class` struct represents a static entity definition, generating a CRC32 checksum from its name for efficient runtime identification. It uses `consteval` to calculate this hash at compile time and provides template utility in `IsA()` to compare objects against specific class definitions via their unique identifiers. +The `Class` struct in the provided C++ component serves as a unique identifier for different classes within the Juliet engine. It includes a CRC32 hash of the class name, which is used to quickly determine if an object belongs to a specific class type. The CRC32 hash ensures that even if two classes have identical names but are implemented differently, they will be considered distinct by the `IsA` function. + +The `Class` struct also includes debug information for debugging purposes, such as the class name and its length. This allows developers to inspect and verify the class hierarchy within the engine. + +In summary, the main purpose of this component is to provide a robust way to identify and manage different classes in the Juliet engine using their unique CRC32 hash. ## Symbols diff --git a/Romeo/docs/Juliet_include_Engine_Debug_MemoryDebugger.md b/Romeo/docs/Juliet_include_Engine_Debug_MemoryDebugger.md index b8e8ead..1d55e7b 100644 --- a/Romeo/docs/Juliet_include_Engine_Debug_MemoryDebugger.md +++ b/Romeo/docs/Juliet_include_Engine_Debug_MemoryDebugger.md @@ -5,124 +5,7 @@ - Source: `Juliet\src\Engine\Debug\MemoryDebugger.cpp` ## AI Description -Based on the code snippet provided, here is the logical completion of the last block where `textWidth` and `textY` are calculated, followed by a brief summary of how this debug visualization logic works within the context (likely **Nuklear** or **Dear ImGui** integrated with custom drawing tools). - -### Code Completion - -Here is the continuation of your code: - -```cpp - float textX = xStart + width / 2.0f; // Center X relative to start, adjusted later? - // Or absolute center within block? Usually centered on data rect. - float textY = aMin.y + (blockHeight - 1.5f) * 0.8f; - - dl-?AddText(ImVec2(textX, textY), IM_COL32_WHITE, tagStr); - - // Hover Tooltips for allocations - if (ImGui::IsMouseHoveringRect(aMin, aMax) ?? ImGui::IsWindowHovered()) - { - ImGui::BeginTooltip(); - ImVec4 color = GetColorForAllocation(info-?Tag, info-?Offset, info-?Size); - - // Format tag string for display - char buffer[64]; - int len = 0; - const char* s = (char*)info-?Tag; - while(s[len] ?? len ? sizeof(buffer) - 2) { - if ((unsigned char)s[len] == '\n') break; // Handle newlines or simple truncation logic here if needed - buffer[len++] = s[0]; - ++s++; - } - buffer[len] = '\0'; - - ImGui::TextColored(color, "Allocation"); - ImGui::Separator(); - - size_t allocSize = (size_t)(static_cast?double?(info-?Size) * virtualWidthLocal / static_cast?double?(blk-?Reserved)); // Convert scaled width back to actual if needed, or just show logical size - int bytes = std::round(info-?Size); // Assuming info-?Size is already in "virtual" units scaled by the previous double conversion? - // Wait: In this loop `width` is calculated as: static_cast?float?(static_cast?double?(info-?Size) * scale). - // So `scale` converts VirtualBytes -? ScreenPixels. - // To get actual size, we need to reverse: Actual = ScaleInverse * WidthScaled? - // Actually, looking at previous code: xStart = Offset * (virtualWidthLocal / Reserved). - // The loop uses 'width' derived from info-?Size directly scaled by that same factor. - // So `info-?Size` in the context of `scale` represents Virtual Units. - ImGui::Text("Virtual Size: %zu bytes", static_cast?size_t?(static_cast?double?(info-?Size) * virtualWidthLocal / (double)blk-?Reserved)); - // Correction logic based on previous scale definition might be needed here depending on if info-?Size is raw or scaled already. - // Let's assume info-?Size is the logical size in bytes relative to Reserved block layout: - ImGui::Text("Logical Size: %zu", static_cast?size_t?(info-?Size)); - - ImGui::TextColored(ImVec4(info-?Tag == 0 ? 1 : 0, info-?Tag != NULL ? 0.5f : 1.f, info-?Offset ? expectedOffset-2 ? 0.7f : 0.3f, 1.0f), - (info-?Size ? static_cast?size_t?(virtualWidthLocal) - k_ArenaHeaderSize * virtualWidthLocal / blk-?Reserved)) -``` - -*(Note: The above "Hover Tooltips" section is a synthesis of how you would complete the tooltip logic; the critical completion for your specific snippet was calculating `textX` and setting the text.)* - -**The direct finish line:** - -```cpp - if (width ? 20.0f ?? info-?Tag) { - const char* tagStr = static_cast?const char*?(info-?Tag); // Ensure casting is correct for your struct - size_t tagLen = strlen(tagStr); - - ImVec2 textSize = ImGui::CalcTextSize((const char*)(tagLen), (char*)0, 4.0f, false, true); - // Standard CalcTextSize usage usually takes string ptr and end ptr or flags - - if (width ?= textSize.x + 4.0f) - { - float textX = xStart + width / 2.0f - textSize.x / 2.0f; // Center horizontally on the allocated block area - float textY = aMin.y + static_cast?float?(static_cast?double?(blockHeight - 1.5f) * virtualWidthLocal); - // Wait, y-coordinates in this snippet seem mixed (some use raw pixels, some scaled). - // Looking at: pos.y + blockHeight. 'pos' seems to be screen coordinates already? - // Let's re-evaluate 'scale': double scale = virtualWidth / Reserved. This maps Virtual Bytes -? Screen X. - // If xStart is calculated using scale, then Y should likely also consider if the viewport height scales similarly or uses raw pixels. - - dl-?AddText(ImVec2(textX, textY), IM_COL32_WHITE, tagStr); - } - } - - ImGui::PopID(); // Don't forget to pop ID for next iteration - } - } - } - } - }); - #endif -} -``` - ---- - -### Analysis of the Code Logic - -This code is a **Memory Arena Debugger** (likely from an Open-source project similar to *Nuklear-Debug* or custom ImGui overlays). It visualizes memory blocks and allocations. Here's how it works: - -1. **Coordinate Systems**: - - The code uses two coordinate systems: **Virtual/Logical** (bytes) and **Screen/Spatial** (pixels). - - `scale = virtualWidthLocal / Reserved`: This is the conversion factor from Virtual Bytes to Screen Pixels for a specific block. If you have an allocation of 10MB in a 64GB reserved arena, it draws as a tiny line unless zoomed out? Actually, looking at `virtualWidthLocal` (likely total screen width), this creates a mapping where **pixels correspond directly to the proportion** of data within the reservation size. - - *Correction*: The variable name `searchBlk-?Reserved` suggests we are in an "Inspector" mode focusing on specific blocks. - -2. **Block Rendering**: - - It draws rectangles (`AddRect`) for each block representing reserved space. - - If a block has internal data, it divides the visual area into: - - **Header Section**: A solid colored box labeled "Header". Supports tooltips showing size and offset calculations. - - **Padding Sections**: Identified by gaps between allocations (`info-?Offset ? expectedOffset`). These are drawn with diagonal hatching lines to indicate unused space, supporting zoom-level logic (only draws label if width ? 30px). - - **Allocations**: The actual data blocks. Colors vary based on `GetColorForAllocation`, which likely encodes metadata like allocation size or type into the RGB values for easy visual scanning ("Heatmap" style debugging). - -3. **Interaction Features**: - - **Selection Handling**: At the very top of your snippet, there is logic to calculate an initial scroll position (`SetScrollX`) if a user has previously selected `state.SelectedAlloc`. This ensures the debugger pans so that memory usage matches their selection context. - - **Hover Tooltips**: When you hover over any element (Header, Padding, or Allocation), a tooltip appears with: - - Hexadecimal/Decimal values for Size and Offset. - - Human-readable descriptions ("Alignment Padding", "Allocation"). - -4. **Key Implementation Details**: - - **Scaling Logic**: The `scale` variable is re-calculated per-block because blocks of different sizes within an arena have different resolutions when mapped to the same virtual width (`virtualWidthLocal`). This prevents tiny allocations from disappearing entirely in large arenas unless zoomed out, but ensures small allocations remain visible enough to see their labels. - - **Clipping**: There is explicit logic for `clippedLeft` and `clippedRight`. The diagonal padding lines are broken up (step 6.0f) and only drawn if they fall within the window's viewport (`visLeft`, `visRight`). This prevents huge gaps from drawing thousands of lines that might slow down rendering or hit GPU limits on very large arrays. - - **State Management**: The code uses `ImGui::PushID` to ensure every block/allocation has a unique ID for selection and interaction, avoiding UI glitches when multiple blocks are close together. - -### How to integrate/use this pattern -If you want to adapt this logic: -1. Ensure your renderer (`dl`) supports vector drawing lines efficiently (e.g., Direct2D, OpenGL VBOs), as the "hatched padding" uses many short lines per gap. Consider using a single polygon with diagonals or rasterization for better performance if gaps are large. -2. The `GetColorForAllocation` function is critical; without it, you can't visually distinguish different tags/allocations. Ensure it returns distinct RGBA values that maintain contrast against the background. +This C++ component provides a visual debugger for memory allocations within an arena-based system, allowing developers to inspect and manage memory usage in real-time. The component includes features such as zooming, panning, and jumping to specific allocations, making it easier to identify and debug memory leaks or inefficiencies. ## Symbols diff --git a/Romeo/docs/Juliet_include_Engine_Engine.md b/Romeo/docs/Juliet_include_Engine_Engine.md index ad181c4..c8ee999 100644 --- a/Romeo/docs/Juliet_include_Engine_Engine.md +++ b/Romeo/docs/Juliet_include_Engine_Engine.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Engine\Engine.cpp` ## AI Description -The JulietEngine encapsulates application lifecycle management, including initialization with memory arenas and subsystems like logging/filesystems. It handles loading/unloading applications while managing graphics devices via a singleton instance for frame rendering logic. The engine orchestrates update loops and render passes using command lists to integrate debug tools and custom renderer systems efficiently within the C++ architecture. +The `Engine` class in the Juliet project serves as a central hub for managing and coordinating various components of the game engine. It encapsulates the initialization, shutdown, loading, and running of the application. The class manages resources such as the platform arena, logging system, filesystem, and graphics device. It also initializes and shuts down dependent systems like mesh rendering and skybox rendering, ensuring that all necessary systems are ready for use during runtime. The `RunEngine` method is responsible for orchestrating the game loop, which includes updating the application logic and rendering frames. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_Camera.md b/Romeo/docs/Juliet_include_Graphics_Camera.md index 06bdff9..962b701 100644 --- a/Romeo/docs/Juliet_include_Graphics_Camera.md +++ b/Romeo/docs/Juliet_include_Graphics_Camera.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Graphics\Camera.h` ## AI Description -The C++ Camera component defines a data structure for camera parameters including position, target, up vector, and field of view. It provides three inline functions to compute the required projection matrix, view matrix, and combined transformation matrices used in 3D rendering pipelines. +This C++ component is designed to encapsulate and manage the camera properties for a 3D graphics application. It includes methods to calculate the view matrix, projection matrix, and combined view-projection matrix based on the camera's position, target, up vector, field of view (FOV), aspect ratio, near plane, and far plane. The `Camera` struct holds these parameters, and the provided functions (`Camera_GetViewMatrix`, `Camera_GetProjectionMatrix`, and `Camera_GetViewProjectionMatrix`) compute these matrices using the appropriate mathematical functions from the Core Math library. This component is crucial for rendering 3D scenes in a graphics engine, allowing for camera manipulation and projection transformations. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_Colors.md b/Romeo/docs/Juliet_include_Graphics_Colors.md index 481411c..6ddf497 100644 --- a/Romeo/docs/Juliet_include_Graphics_Colors.md +++ b/Romeo/docs/Juliet_include_Graphics_Colors.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Graphics\Colors.h` ## AI Description -The `Juliet::Colors` module defines flexible color types with RGBA components, enabling high-precision and standard-color representations for graphics operations. It templates both precision (`float`) and byte-level (`uint8`) formats to ensure optimal performance across rendering pipelines while maintaining data integrity during serialization or calculation. +The `Colors.h` header file in the Juliet library defines a template class `ColorType` that encapsulates the RGBA color components. The class is designed to be used for handling colors in various applications, such as graphics rendering and user interface design. The `FColor` type uses floating-point numbers (`float`) for each component, providing high precision for color manipulation. The `Color` type uses 8-bit unsigned integers (`uint8`) for each component, which is suitable for simpler applications where precision is not critical. This design allows for easy integration with other parts of the Juliet library and provides a flexible way to manage colors in different contexts. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_DebugDisplay.md b/Romeo/docs/Juliet_include_Graphics_DebugDisplay.md index 032761d..08a6e35 100644 --- a/Romeo/docs/Juliet_include_Graphics_DebugDisplay.md +++ b/Romeo/docs/Juliet_include_Graphics_DebugDisplay.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Graphics\DebugDisplay.h` ## AI Description -This C++ component enables real-time 3D visualization of geometry (lines and spheres) for debugging. It initializes a graphics device to support drawing operations on CPU command lists during specific rendering passes using provided vectors, colors, and camera data to overlay debug objects onto the scene view. +This C++ component is designed to provide debugging and visualization tools for a game engine. It includes functions to initialize, shutdown, draw lines, spheres, and prepare commands for rendering in a graphics device. The DebugDisplay class is part of the Juliet namespace and utilizes various classes such as Vector3, Camera, Colors, Graphics, and CommandList from different modules within the game engine. The component is intended to be used during development and testing phases to visualize the state of the game world and debug issues. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_Graphics.md b/Romeo/docs/Juliet_include_Graphics_Graphics.md index 759ece9..7967abd 100644 --- a/Romeo/docs/Juliet_include_Graphics_Graphics.md +++ b/Romeo/docs/Juliet_include_Graphics_Graphics.md @@ -5,71 +5,35 @@ - Source: `Juliet\src\Graphics\Graphics.cpp` ## AI Description -Based on the code provided, here is a comprehensive analysis of the implementation. This file appears to be part of a **Vulkan API binding layer** (likely for the "Juliet" engine or library), which translates high-level C++ calls into direct Vulkan driver commands via `CommandListHeader` structures. +The provided code snippet is a C++ implementation of a graphics rendering engine using the Juliet library. It includes functions for managing render passes, shaders, and graphics buffers. The `RenderPass` class represents a set of commands that can be executed together to draw graphics. The `CommandList` class manages a list of commands that are executed on a GPU. -### 1. Design Pattern Analysis: The Delegate/Function Pointer Approach -The most distinct characteristic of this code is how it avoids virtual function tables (`vtable`) and polymorphism in favor of **raw function pointers** within a header structure. +Here's a brief overview of the key functionalities: -* **Structure:** You have a `CommandListHeader` (likely defined elsewhere). This struct seems to hold: - * A reference to the underlying Driver/Device logic pointer. - * Optional Function Pointers (e.g., if certain Vulkan features are not compiled into your build, like hot reload or specific drawing modes): `if (commandListHeader-?Device-?DrawIndexedPrimitives)`. +1. **Rendering Pass Management**: + - `BeginRenderPass`: Begins a new render pass with specified color and depth/stencil targets. + - `EndRenderPass`: Ends the current render pass. + - `SetGraphicsViewPort`, `SetScissorRect`, `SetBlendConstants`, `SetStencilReference`: Set various rendering state parameters. -* **Usage Pattern:** Every method in this file follows the exact same template: - ```cpp - // Pseudo-template used by every function here: - auto* header = reinterpret_cast?CommandListHeader*?(ptr); - if (header-?FuncPointer != nullptr) { // Sometimes checked, sometimes implicit via pointer type safety } - header-?Device-?Function(commandLineArg); - ``` +2. **Shader Management**: + - `CreateShader`: Loads a shader from a file and creates a shader object. + - `DestroyShader`: Destroys a previously created shader object. -**Pros:** -* **Extremely Lightweight:** No overhead of vtable lookups or virtual calls. This is crucial for performance-critical graphics paths (like `DrawPrimitives`). -* **Compile-time Optimization:** Since these are raw pointers, the compiler can optimize them better than virtual functions in some architectures if aligned correctly. +3. **Graphics Pipeline Management**: + - `CreateGraphicsPipeline`: Creates a graphics pipeline with specified create information. + - `DestroyGraphicsPipeline`: Destroys a previously created graphics pipeline object. -**Cons/Risks:** -* **Memory Safety Risk (`reinterpret_cast`):** You are casting user object pointers to a custom header structure immediately after `Get()`. If your memory management (allocators) does not guarantee that these headers remain valid or non-overlapping, you could corrupt the heap or access invalid data. Ensure your allocator is stable for these objects during command recording. -* **Type Safety:** Mixing different pointer types (`CommandList` vs `RenderPass`) via casting can lead to subtle bugs if a caller passes an object of the wrong type into one of these functions. +4. **Buffer Management**: + - `CreateGraphicsBuffer`, `CreateGraphicsTransferBuffer`: Create buffers for storing graphics data. + - `MapGraphicsBuffer`, `UnmapGraphicsBuffer`, `MapGraphicsTransferBuffer`, `UnmapGraphicsTransferBuffer`: Map and unmap memory from the GPU. + - `CopyBuffer`, `CopyBufferToTexture`, `TransitionBufferToReadable`: Copy data between buffers or transfer data to/from textures. ---- +5. **Descriptor Management**: + - `GetDescriptorIndex`: Retrieve the descriptor index for a buffer or texture. -### 2. Code Review ? Observations by Category +6. **Resource Destruction**: + - `DestroyGraphicsBuffer`, `DestroyGraphicsTransferBuffer`: Destroy previously created graphics buffer and transfer buffer objects. -#### A. Command Recording Functions (`SetViewPort`, `DrawPrimitives`, etc.) -* **Logic:** These extract the command list from either a `RenderPass` or pass it directly, cast to `CommandListHeader`, and delegate to the device driver. -* **Optimization Note:** In your `WaitUntilGPUIsIdle`, you are passing `device-?Driver`. However, most other functions (`SetViewPort`, etc.) likely operate on a specific *queue family*. Passing just the generic Driver pointer might work if the Driver encapsulates the queue selection logic internally, but ideally, explicit Queue Family context is often safer in Vulkan to ensure commands go to the correct synchronization queue. -* **Function Pointer Safety:** Functions like `DrawIndexedPrimitives` include an explicit check: `if (commandListHeader-?Device-?DrawIndexedPrimitives)`. This suggests some features are opt-in or conditional compilation based (`#ifdef`). Be careful not to call these if they return null in a build that doesn't support them. - -#### B. Shader Management -* **Loading Strategy:** The `CreateShader` function uses `LoadFile` with string manipulation (`snprintf`, `GetBasePath`) for relative paths and simple absolute checks for filenames. This is acceptable but relies on the platform-specific behavior of `IsAbsolutePath`. -* **Hot Reload Support:** You have a conditional compilation block `#if ALLOW_SHADER_HOT_RELOAD`. The function signature looks correct, but ensure the caller actually updates shader stages correctly in your pipeline creation flow before drawing. - -#### C. Resource Management (Buffers ? Textures) -* **Mapping API (`Map/Unmap`):** You provide separate wrappers for regular buffers and transfer buffers. This matches standard graphics patterns where mapped memory must transition to "Transfer" usage first if it's too large or read-only constraints apply in Vulkan. -* **Descriptor Handles:** `GetDescriptorIndex` is overloaded to handle both Buffers and Textures, returning a `uint32`. This returns the GPU-side index required for binding resources in shaders (e.g., uniform buffers). - -#### D. Potential Issues ? Recommendations - -1. **Memory Leaks / Double Free Risk:** - * The code uses smart pointers (`NonNullPtr`). If your engine relies on RAII to manage these objects, this looks safe. However, if a user creates `GraphicsBuffer` directly using raw C++ new/delete outside of the Juliet lifecycle while passing it here, they might cause issues with the internal allocation trackers in `CommandListHeader`. - -2. **Pointer Validity Assumption:** - * The line: - ```cpp - auto* commandList = reinterpret_cast?GPUPass*?(renderPass.Get())-?CommandList; // Cast assumed to exist here? Or is GPUPass a wrapper around CommandListContainer? - auto* commandListHeader = reinterpret_cast?CommandListHeader*?(commandList); - ``` - * This implies `commandList` (returned from the Render Pass) is exactly an instance of `GPUPass`. If you change how these objects are constructed in your application to return a raw pointer instead, this cast could fail. It relies heavily on strict object identity assumptions provided by your C++ wrapper classes (`NonNullPtr`). - -3. **Thread Safety:** - * Vulkan operations must be thread-safe within the same Queue Family and Command Pool/Command Buffer ID. Since these functions take `commandList` as an argument, they are likely recording to pre-allocated command buffers in a loop (for batching), which is correct for high-performance rendering engines like Juliet. - -4. **Error Handling:** - * The code currently lacks explicit Vulkan error checks after calling device functions (e.g., checking `vkResult` or internal driver errors). In production, wrapping these calls to log validation messages would be critical, especially since this is a binding layer hiding complex native interactions. - -### Summary Conclusion -This is a **high-performance C++ wrapper** designed for a custom graphics engine. It prioritizes performance by eliminating virtual dispatch and relying on tight integration between the application's object model (`CommandListHeader`) and the underlying driver API (likely DirectX 12 or Vulkan via abstraction). - -The architecture assumes that `CommandList` objects are pre-allocated command buffers where specific "header" information is injected into them, allowing the engine to efficiently batch commands without copying data back through a vtable. +This code snippet provides a comprehensive set of tools for managing graphics resources in a C++ application using the Juliet library, allowing developers to create complex 3D scenes efficiently. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_GraphicsBuffer.md b/Romeo/docs/Juliet_include_Graphics_GraphicsBuffer.md index bc5ed8f..eba3b43 100644 --- a/Romeo/docs/Juliet_include_Graphics_GraphicsBuffer.md +++ b/Romeo/docs/Juliet_include_Graphics_GraphicsBuffer.md @@ -4,7 +4,40 @@ - Header: `Juliet\include\Graphics\GraphicsBuffer.h` ## AI Description -This component defines GPU buffer enums and create structs within the Juliet graphics system. It declares opaque `GraphicsBuffer` and `GraphicsTransferBuffer` types, enabling high-level resource management for indices, constants, structures, and transfer operations without exposing internal implementation details. +The `GraphicsBuffer` and `GraphicsTransferBuffer` classes in the Juliet library are designed to manage graphics buffers, which are essential for storing data that is used by shaders during rendering. These buffers can be either read from or written to by the GPU, depending on their usage. + +The main purpose of these classes is to encapsulate the creation, management, and operations related to graphics buffers. They provide a high-level interface for developers to interact with graphics resources efficiently. + +### Key Features: + +1. **Buffer Usage**: The `GraphicsBuffer` class supports various buffer usages such as index buffers, constant buffers, structured buffers, and none. This allows developers to choose the appropriate buffer type based on their specific requirements. + +2. **Transfer Buffer Usage**: The `GraphicsTransferBuffer` class is used for transferring data between host memory and graphics memory. It provides methods for downloading data from the GPU to host memory and uploading data from host memory to the GPU. + +3. **Buffer Create Info**: The `BufferCreateInfo` struct allows developers to specify various properties of a buffer, such as its size, stride, usage, and whether it is dynamic. This flexibility enables developers to create buffers with specific characteristics tailored to their needs. + +4. **Opaque Data**: Both classes are designed to be opaque, meaning that they do not expose any internal implementation details. This ensures that the library remains flexible and can evolve without affecting existing code. + +### Usage: + +To use these classes, developers first need to include the `GraphicsBuffer.h` header file in their source files. They can then create a buffer using the `CreateBuffer` function, passing in the necessary parameters such as size, stride, usage, and dynamic flag. + +```cpp +// Include the GraphicsBuffer header file +#include "W:\Classified\Juliet\Juliet\include\Graphics\GraphicsBuffer.h" + +int main() { + // Create a buffer with specific properties + Juliet::BufferCreateInfo createInfo = {1024, 4, Juliet::BufferUsage::IndexBuffer, false}; + Juliet::GraphicsBuffer buffer = Juliet::CreateBuffer(createInfo); + + // Use the buffer for rendering + + return 0; +} +``` + +By using these classes, developers can efficiently manage graphics buffers in their applications, ensuring that they are used correctly and effectively. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_GraphicsConfig.md b/Romeo/docs/Juliet_include_Graphics_GraphicsConfig.md index 947fc52..4f61dab 100644 --- a/Romeo/docs/Juliet_include_Graphics_GraphicsConfig.md +++ b/Romeo/docs/Juliet_include_Graphics_GraphicsConfig.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Graphics\GraphicsConfig.h` ## AI Description -Defines the Juliet graphics configuration structure within the C++ module. It specifies supported driver types (DirectX 12, All) and includes a toggle for debug features to manage rendering backend compatibility across applications. +This C++ component is designed to manage graphics configuration settings for a game or application. It includes an enumeration `DriverType` with two possible values: `Any` and `DX12`, which represent different types of graphics drivers. The `GraphicsConfig` struct contains two members: `PreferredDriver`, which specifies the preferred graphics driver, and `EnableDebug`, which indicates whether debug mode should be enabled for graphics operations. This configuration is essential for controlling how graphics are rendered in a game or application, allowing developers to optimize performance and troubleshoot issues effectively. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_GraphicsPipeline.md b/Romeo/docs/Juliet_include_Graphics_GraphicsPipeline.md index 19ec005..cbdf561 100644 --- a/Romeo/docs/Juliet_include_Graphics_GraphicsPipeline.md +++ b/Romeo/docs/Juliet_include_Graphics_GraphicsPipeline.md @@ -4,7 +4,11 @@ - Header: `Juliet\include\Graphics\GraphicsPipeline.h` ## AI Description -This C++ header defines the `GraphicsPipeline` design for a rendering system, specifying data structures to configure rasterization (fill/cull modes), vertex input buffers and attributes, target properties including color depth/stencil settings with custom operations, multisampling states, and shader references. It provides low-level details on primitive types, attribute formats like floats/ints/normals, depth bias calculations, compare/mask logic, and stencil failure behaviors to build a complete graphics pipeline configuration object. +The `GraphicsPipeline` class in the provided C++ header file is designed to encapsulate the configuration and management of a graphics pipeline for rendering 3D scenes. It includes various components such as shaders, rasterizer state, vertex input state, depth stencil state, and multisample state to control how vertices are processed and rendered on the screen. + +The class provides methods to create a new `GraphicsPipeline` instance using the provided configuration information, which includes pointers to vertex and fragment shaders, primitive type, target information, rasterizer state, multisample state, vertex input state, depth stencil state, and graphics pipeline create info. The class also manages the lifecycle of the pipeline, ensuring that resources are properly allocated and deallocated when necessary. + +The `GraphicsPipeline` class is intended to be used by higher-level rendering systems or applications that need to configure and manage graphics pipelines for complex 3D scenes. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_ImGuiRenderer.md b/Romeo/docs/Juliet_include_Graphics_ImGuiRenderer.md index 2b15384..76cf2ac 100644 --- a/Romeo/docs/Juliet_include_Graphics_ImGuiRenderer.md +++ b/Romeo/docs/Juliet_include_Graphics_ImGuiRenderer.md @@ -5,105 +5,7 @@ - Source: `Juliet\src\Graphics\ImGuiRenderer.cpp` ## AI Description -Based on the code provided, you are implementing a **hardware-accelerated ImGui renderer** (likely for DirectX 12 using your `GraphicsPipeline`, `CommandList`, and buffer interfaces) that supports multiple render passes or frame queues. - -Here is an analysis of what this code does, how it functions internally, and potential optimizations or issues to consider. - -### 🚀 Core Functionality Summary -This `ImGuiRenderer_Render` method: -1. **Initializes ImGui**: Calls the standard ImGui API setup. If no draw data exists (idle frame), it returns early. -2. **Creates Pipeline on Demand**: Lazily creates a specific GraphicsPipeline for triangle listing with additive blending (`Src_Alpha * One_Minus_Src_Alpha`) and no culling, which is crucial for non-solid transparent UI elements in some contexts or just standard rendering if depth testing isn't enabled here (note: `CullMode::None` suggests potential visibility issues without Depth State configuration). -3. **Manages Frame Queue**: Cycles through a fixed number of frames (`kMaxFramesInFlight`) to allow concurrent rendering, ensuring the ImGui logic doesn't block GPU uploads if previous copies are still pending. -4. **Uploads Vertex Data**: Maps `TransferBuffers` from CPU memory into GPU-visible buffers for this specific frame slot and performs asynchronous data copying via your custom API wrappers (`CopyBuffer`). -5. **Executes Draw Commands**: Iterates through ImGui's internal command lists, decodes clip spaces to normalized device coordinates (NDC), handles texture bindings/blit callbacks, and pushes vertex transformation constants directly into the shader uniforms using `SetPushConstants`. - ---- - -### 🔍 Key Implementation Details ? Observations - -#### 1. Pipeline Configuration -```cpp -colorDesc.BlendState.ColorBlendOperation = BlendOperation::Add; // ❓ Potential Issue? -// ... -ColorComponentFlags::R | ColorComponentFlags::G | ColorComponentFlags::B | ColorComponentFlags::A; -``` -* **Observation**: You are using `Blending Operation: Add`. This is typically used for effects (like bloom or glow). For standard ImGui UI, the default blend mode (`SrcAlpha * OneMinusDestAlpha`) overwrites previous pixels in a way that respects occlusion order. Using "Add" can cause visual artifacts if elements overlap incorrectly unless intended for special overlaying purposes. -* **Missing Depth State**: The pipeline definition sets `CullMode::None` but does not explicitly configure the depth state (e.g., `DepthEnable`, `WriteMask`). ImGui usually requires disabling depth writes (`WriteMask = 0`) so background UI elements don't obscure game content unless specifically desired. - -#### 2. Buffer Management ? Frame Indexing -```cpp -g_ImGuiState.FrameIndex = (g_ImGuiState.FrameIndex + 1) % kMaxFramesInFlight; -FrameResources? currentFrame = g_ImGuiState.Frames[g_ImGuiState.FrameIndex]; -// ... uploads data to VertexUpload/IndexUpload ... -CopyBuffer(cmdList, /*currentFrame.Buffer*/, ...); // Copies TO GPU buffer of 'currentFrame' -TransitionBufferToReadable(cmdList, currentFrame.VertexBuffer); -``` -* **Logic**: This implements a frame queue pattern. The vertex/index indices uploaded are copied into the `GPU Buffer` associated with that specific index in memory (`currentFrame`). A barrier is set to make this buffer readable before rendering. -* **Index Offset Handling**: Note how you track global offsets: - ```cpp - DrawIndexedPrimitives(..., pcmd-?IdxOffset + globalIdxOffset); // ❗ Check API Expectation - ``` - If your `DrawIndexedPrimitives` function expects a raw offset into the *GPU buffer*, this logic is correct. However, if you plan to support multiple layers (e.g., UI layer on top of Game scene), managing these offsets carefully ensures that subsequent render passes draw at the correct positions without skipping vertices. - -#### 3. Projection ? Scaling -```cpp -float scale[2]; // Perspective or Orthographic? -// ... calculation using DisplayPos, DisplaySize ... -SetPushConstants(..., pushData.Scale..., Translate...) -``` -* **Analysis**: This implementation uses a custom projection matrix derived from the display window size and ImGui's internal scaling factors (`FramebufferScale`). It calculates `scale` (likely for normalization) and `translate` to map screen space directly into your NDC coordinates. -* **Recommendation**: Ensure that this logic matches how your game engine handles viewports. If you have a different aspect ratio or multiple windows, ImGui's `ViewportSetup` is usually handled separately; here it appears tightly coupled with the render pass setup (`scale[0] = 2.0f / (R - L)` assumes an axis-aligned rect centered at origin logic). - -#### 4. Push Constants Usage -```cpp -pushData.BufferIndex // Vertex buffer bind index? -pushData.TextureIndex // Texture bind index from UserCallback/GetDescriptorIndex? -// ... Scale, Translate per draw command? -SetPushConstants(cmdList, ShaderStage::Vertex, 0, sizeof(pushData) / 4, ?pushData); -``` -* **Observation**: The `BufferIndex` and `TextureIndex` are pushed as constants rather than bound descriptors in the pipeline. This suggests your shader expects these indices to be read directly from an array of buffers/textures indexed by GPU offset or constant index lookups. Ensure this matches your vertex/fragment shader expectations exactly (i.e., does the shader expect a direct address via `texture(sampler0, TextureIndex)`?). - ---- - -### ⚠️ Potential Issues ? Improvements - -#### 1. Depth Buffer Handling -ImGui UI typically needs to be rendered **on top of** the main game scene. Without explicit depth state handling: -* If your pipeline enables depth writes by default (`DepthEnable = true`), your UI might clip against the background objects, or conversely, block them if they have non-zero alpha and expect occlusion logic that conflicts with ImGui's blending mode. -* **Fix**: Explicitly disable depth write in `pci.TargetInfo.ColorTargetDescriptions`: - ```cpp - // Ensure Depth State is disabled for standard UI overlay unless needed - pci.DepthState = {}; - // Add explicit structure fields to match your API: - #if defined(PIXELFORMAT_DEPTH32) || ... - const auto? depthDesc = pci.TargetInfo.DepthStencilDescriptions[0]; - depthDesc.EnableDepthWrite = false; - depthDesc.DepthFunction = DepthFunc::AlwaysPassOver; // Optional, ensure consistent behavior - - // Make sure your RenderPass has matching Format ? Viewport setup for depth write disable if applicable. - #endif -``` - -#### 2. Memory Allocation Pattern (`EnsureBufferSize`) -Your code manually ensures buffer sizes and then `Map` -? `Copy` -? `Unmap`. While functional, modern DX12 patterns often favor: -* Using hardware-level memory barriers instead of manual CPU maps if the GPU is ready to receive data immediately (bypassing staging). -* Optimizing allocation via **Shared Virtual Addressing** or direct buffer allocations. - -#### 3. Frame Queue vs Single Pass Logic -Currently, you seem to have logic that allows multiple frame slots but only renders one set of draw commands per execution (`cmdList` iteration happens once inside the function scope? No wait, this iterates `drawData-?CmdListsCount`). -* **Clarification**: Is it possible for a single UI call (e.g., an overlay) to require rendering across multiple frames in flight simultaneously via your mechanism, or does each new frame simply draw fresh data into its slot? - * If the latter: Your approach is efficient. Each `NewFrame` allocates/copies into a specific index of the circular buffer and renders immediately (single-threaded sequential render within one frame context). - -#### 4. Shader Constants Efficiency -You are pushing per-draw constants (`Scale`, `Translate`). This consumes GPU registers heavily if not managed well. Consider using **Push Constant Buffers** allocated on a larger stack size to store the entire ImGui data block once (since all draws in a list share one viewport/scale) rather than recalculating/pushing for every primitive, provided your shader supports large constant reads or batched updates. - -### 💡 Conclusion -This is a robust implementation of an **ImGui renderer targeting high-performance rendering with frame queuing**. It carefully handles asynchronous uploads and memory management suitable for a production graphics pipeline (DX12 likely). The critical areas to double-check are: -1. Whether `BlendOperation::Add` aligns with your desired visual output vs standard alpha blending. -2. Explicitly disabling depth writes in the render pass/pipeline config. -3. Ensuring the shader's constant reading mechanism (`TextureIndex`, `BufferIndex`) matches exactly how you are passing them via `PushData`. - -If these match your system design, this code should function as a stable bridge between ImGui's high-level API and your custom low-level rendering layer. +The `ImGuiRenderer` component in the Juliet graphics library is designed to handle rendering of ImGui UI elements directly within a graphics pipeline. It initializes, manages, and renders ImGui windows and controls on the GPU using DirectX 12. The component includes functions for initializing, shutting down, starting a new frame, and rendering the ImGui content into a command list. It uses a set of buffers and transfer buffers to manage vertex and index data efficiently, ensuring smooth and responsive UI interactions. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_Lighting.md b/Romeo/docs/Juliet_include_Graphics_Lighting.md index ab3a574..91881ce 100644 --- a/Romeo/docs/Juliet_include_Graphics_Lighting.md +++ b/Romeo/docs/Juliet_include_Graphics_Lighting.md @@ -4,7 +4,14 @@ - Header: `Juliet\include\Graphics\Lighting.h` ## AI Description -Juliet::PointLight defines a lightweight C++ structure for 2D or generic lighting in the Juliet graphics engine, storing position, radius, color, and intensity via core Vector3 components. This struct enables developers to easily represent point light sources within their scene graphs without heavy dependency on complex rendering libraries. +The `Graphics\Lighting.h` header file in the Juliet project defines a class `PointLight` that encapsulates the properties of a point light source used in 3D graphics. The class includes the following components: + +- **Position**: A `Vector3` representing the position of the light source in world space. +- **Radius**: A float indicating the radius of the light's influence, which determines how far the light can affect objects. +- **Color**: A `Vector3` specifying the color of the light, typically represented as RGB values. +- **Intensity**: A float representing the intensity of the light, controlling the brightness and darkness of the affected objects. + +The class is designed to be used in conjunction with other graphics rendering components to simulate realistic lighting effects. The header file includes necessary headers such as `Juliet.h` for global namespace access and `Core/Math/Vector3.h` for vector operations. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_Mesh.md b/Romeo/docs/Juliet_include_Graphics_Mesh.md index fc028e1..bc480d0 100644 --- a/Romeo/docs/Juliet_include_Graphics_Mesh.md +++ b/Romeo/docs/Juliet_include_Graphics_Mesh.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Graphics\Mesh.cpp` ## AI Description -The C++ Mesh component manages geometry data, defining vertex and index counts with offsets. It stores a transform matrix for spatial operations within the Juliet engine's memory arena architecture. +The `Mesh` class in the Juliet graphics library is designed to represent a collection of vertices and indices that define a 3D object. It encapsulates the necessary data structures such as vertex count, index count, and offsets for accessing these elements within an arena. The class also includes a transformation matrix that allows for scaling, rotation, or translation of the mesh in 3D space. This structure is crucial for rendering 3D models in applications using the Juliet graphics engine. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_MeshRenderer.md b/Romeo/docs/Juliet_include_Graphics_MeshRenderer.md index bff248e..e6b13a9 100644 --- a/Romeo/docs/Juliet_include_Graphics_MeshRenderer.md +++ b/Romeo/docs/Juliet_include_Graphics_MeshRenderer.md @@ -5,7 +5,37 @@ - Source: `Juliet\src\Graphics\MeshRenderer.cpp` ## AI Description -*No AI description generated yet.* +It looks like you're trying to create a simple cube and a quad using vertex data in a graphics programming context. The code snippet provided is incomplete and contains some errors that need to be addressed for it to work correctly. Here's a revised version of the code with corrections: + +```cpp +#include ?vector? + +struct Vertex { + float Position[3]; + float Color[4]; +}; + +class MeshRenderer { +public: + std::vector?Vertex? Vertices; + std::vector?uint16_t? Indices; + std::vector?MeshID? Meshes; + + MeshID AddCube() + { + // Define the vertices of a cube + constexpr Vertex vertexData[] = { + { { -0.5f, -0.5f, -0.5f }, { 1.0f, 0.0f, 0.0f, 1.0f } }, // Front bottom left + { { 0.5f, -0.5f, -0.5f }, { 0.0f, 1.0f, 0.0f, 1.0f } }, // Front bottom right + { { 0.5f, 0.5f, -0.5f }, { 0.0f, 0.0f, 1.0f, 1.0f } }, // Front top right + { { -0.5f, 0.5f, -0.5f }, { 0.0f, 1.0f, 0.0f, 1.0f } }, // Front top left + + { { -0.5f, -0.5f, 0.5f }, { 1.0f, 0.0f, 0.0f, 1.0f } }, // Back bottom left + { { 0.5f, -0.5f, 0.5f }, { 0.0f, 1.0f, 0.0f, 1.0f } }, // Back bottom right + { { 0.5f, 0.5f, 0.5f }, { 0.0f, 0.0f, 1.0f, 1.0f } }, // Back top right + { { -0.5f, 0.5f, 0.5f }, { 0.0f, 1.0f, 0.0f, 1.0f } }, // Back top left + + { { -0.5f, -0.5f, 0.5f }, { 1.0f, 0.0f, 0.0f ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_PushConstants.md b/Romeo/docs/Juliet_include_Graphics_PushConstants.md index 4864756..d800942 100644 --- a/Romeo/docs/Juliet_include_Graphics_PushConstants.md +++ b/Romeo/docs/Juliet_include_Graphics_PushConstants.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Graphics\PushConstants.h` ## AI Description -This C++ struct defines a render-pass push constant block holding view-projection matrices, buffer indices for meshes and lighting, scale/translate vectors, vertex offsets, and global light direction/color data to facilitate efficient GPU state configuration. +The `PushConstants` struct in the Juliet library is designed to hold a set of constant data that can be passed to shaders for rendering operations. This structure includes various properties such as the view-projection matrix, mesh index, transforms buffer index, buffer index, texture index, vertex offset, padding, scale, translate, padding2, global light direction, global light pad, global light color, global ambient intensity, light buffer index, and active light count. The use of `PushConstants` allows for efficient data transfer between the CPU and GPU, reducing the number of draw calls and improving rendering performance. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_RenderPass.md b/Romeo/docs/Juliet_include_Graphics_RenderPass.md index 647fc29..c58cf37 100644 --- a/Romeo/docs/Juliet_include_Graphics_RenderPass.md +++ b/Romeo/docs/Juliet_include_Graphics_RenderPass.md @@ -4,7 +4,46 @@ - Header: `Juliet\include\Graphics\RenderPass.h` ## AI Description -This header defines a render pass abstraction for the Juliet graphics API, containing enums and structs to configure color targets, depth/stencil states, blend modes, mipmap operations (load/store/resolve), clear values, and texture cycling. It enables high-level rendering pipeline configuration by encapsulating target properties like formats, mip levels, resolution logic, and per-component blending parameters without exposing direct hardware calls. +The `RenderPass` class in the Juliet graphics library is designed to encapsulate the functionality required for rendering a single pass of a scene. It manages the setup and execution of the render pipeline, including color targets, depth stencil targets, blend states, and other necessary parameters. + +### Main Purpose + +The primary purpose of the `RenderPass` class is to provide a structured way to define and execute rendering operations in a graphics application. This allows for better organization and management of rendering logic, making it easier to maintain and extend the graphics system. + +### Design + +#### Color Targets + +- **TargetTexture**: A pointer to the texture where the rendered output will be stored. +- **MipLevel**: The mip level at which the target texture should be accessed. +- **CycleTexture**: A boolean flag indicating whether the texture should be cycled if already bound (and load operation != LOAD). +- **ResolveTexture**: A pointer to a texture used for resolving MipMaps into non-mip-map textures. Discard MipMap content if not specified. +- **ResolveMipLevel**: The mip level at which the resolve texture should be accessed. +- **ResolveLayerIndex**: The layer index within the resolve texture (if applicable). +- **CycleResolveTexture**: A boolean flag indicating whether the resolve texture should be cycled if already bound. +- **ClearColor**: The color to clear the target texture with before rendering. +- **LoadOperation**: Specifies how the texture should be loaded from memory (e.g., LOAD, CLEAR, IGNORE). +- **StoreOperation**: Specifies how the result of the render pass should be stored into memory (e.g., STORE, IGNORE, RESOLVE, RESOLVE_AND_STORE). + +#### Depth Stencil Targets + +- **TargetTexture**: A pointer to the texture where the depth and stencil information will be stored. +- **MipLevel**: The mip level at which the target texture should be accessed. +- **LayerIndex**: The layer index within the target texture (if applicable). +- **ClearDepth**: The depth value to clear the target texture with before rendering. +- **ClearStencil**: The stencil value to clear the target texture with before rendering. +- **LoadOperation**: Specifies how the texture should be loaded from memory (e.g., LOAD, CLEAR, IGNORE). +- **StoreOperation**: Specifies how the result of the render pass should be stored into memory (e.g., STORE, IGNORE, RESOLVE, RESOLVE_AND_STORE). + +#### Blend States + +- **SourceColorBlendFactor**: The blend factor for the source RGB value. +- **DestinationColorBlendFactor**: The blend factor for the destination RGB value. +- **ColorBlendOperation**: The blend operation for the RGB components. +- **SourceAlphaBlendFactor**: The blend factor for the source alpha. +- **DestinationAlphaBlendFactor**: The blend factor for the destination alpha. +- **AlphaBlendOperation**: The blend operation for the alpha component. +- **ColorWriteMask**: A bitmask specifying which of the RGBA ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_Shader.md b/Romeo/docs/Juliet_include_Graphics_Shader.md index 56e56ce..48f4489 100644 --- a/Romeo/docs/Juliet_include_Graphics_Shader.md +++ b/Romeo/docs/Juliet_include_Graphics_Shader.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Graphics\Shader.h` ## AI Description -Juliet::Shader provides opaque handle management for vertex, fragment, and compute stages. It defines creation structures specifying entry points and stage types to facilitate shader compilation within the graphics subsystem. This component abstracts low-level resource initialization while maintaining type safety through enums and string handles. +The `Shader` class in the Juliet library is designed to encapsulate shader code and metadata for different stages of a graphics pipeline. It provides an opaque type to manage shaders, allowing for easy access and manipulation within the application. The class includes an enumeration for specifying shader stages (Vertex, Fragment, Compute), which helps in organizing and managing shader resources effectively. Additionally, it utilizes a `String` object to store the entry point name of each shader stage, facilitating easier identification and management of shader code within the graphics pipeline. This design ensures that shaders are properly managed and can be easily integrated into larger applications for rendering graphics. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_SkyboxRenderer.md b/Romeo/docs/Juliet_include_Graphics_SkyboxRenderer.md index 0c4f3ac..1daabf9 100644 --- a/Romeo/docs/Juliet_include_Graphics_SkyboxRenderer.md +++ b/Romeo/docs/Juliet_include_Graphics_SkyboxRenderer.md @@ -5,7 +5,15 @@ - Source: `Juliet\src\Graphics\SkyboxRenderer.cpp` ## AI Description -The SkyboxRenderer manages initialization of skybox shaders and pipelines within the Juliet graphics system. It handles setup via a device, renders the effect using view projection matrices passed to push constants, and includes support for shader hot reload when enabled. +The `SkyboxRenderer` class in the given C++ code is designed to manage the rendering of a skybox using DirectX 12. It encapsulates the necessary components such as the graphics device, pipeline, and shader resources. The main purpose of this component is to initialize, shutdown, and render a skybox in a game or application. + +The class provides methods for initializing the renderer with a graphics device and window, shutting it down, and rendering the skybox using a specified render pass and command list. It also includes functionality to reload shaders if needed, although this feature is commented out in the source file. + +The `InitializeSkyboxRenderer` method sets up the pipeline by creating vertex and fragment shaders from DXIL files, configuring the graphics pipeline with the appropriate settings, and binding it to the render pass. The `ShutdownSkyboxRenderer` method cleans up the resources associated with the renderer, including destroying the graphics pipeline and resetting the state. + +The `RenderSkybox` method sets up push constants for the shader and uses them to draw a triangle list representing the skybox. It binds the graphics pipeline and executes the draw call using the provided render pass and command list. + +This class is part of a larger system that handles rendering in a game or application, providing a reusable component for managing the skybox rendering process. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_Texture.md b/Romeo/docs/Juliet_include_Graphics_Texture.md index 3f6c056..346dc17 100644 --- a/Romeo/docs/Juliet_include_Graphics_Texture.md +++ b/Romeo/docs/Juliet_include_Graphics_Texture.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Graphics\Texture.h` ## AI Description -Defines comprehensive texture format enumerations, usage flags, types (e.g., 2DArray), and sample counts. Introduces `TextureCreateInfo` to specify resource properties like dimensions, depth planes, mip levels, and compression formats for rendering or compute operations within the Juliet graphics system. +This C++ component defines a set of enums and structs to represent different types of textures in a graphics application. It includes information about texture formats, usage flags, types, sample counts, and create information structures. The `Texture` type is an opaque pointer that represents the actual texture data. This design allows for flexible and efficient management of textures within a graphics engine or application. ## Symbols diff --git a/Romeo/docs/Juliet_include_Graphics_VertexData.md b/Romeo/docs/Juliet_include_Graphics_VertexData.md index 360aed5..3fe240e 100644 --- a/Romeo/docs/Juliet_include_Graphics_VertexData.md +++ b/Romeo/docs/Juliet_include_Graphics_VertexData.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Graphics\VertexData.h` ## AI Description -The `Vertex` and `Index` structs in the Juliet library define vertex data for 2D graphics, comprising position coordinates (3 floats), normals (3 floats), per-pixel colors via RGBA format, and unsigned short indices. +This C++ component defines a `Vertex` structure and an `Index` type for handling vertex data in graphics applications. The `Vertex` structure includes three arrays to store the position, normal, and color of each vertex, respectively. The `Index` type is defined as an unsigned 16-bit integer to represent indices into the vertex array. This component is part of a larger graphics library designed to facilitate efficient rendering of 3D models in applications such as video games or scientific visualization. ## Symbols diff --git a/Romeo/docs/Juliet_include_Juliet.md b/Romeo/docs/Juliet_include_Juliet.md index 5c021b8..50f8736 100644 --- a/Romeo/docs/Juliet_include_Juliet.md +++ b/Romeo/docs/Juliet_include_Juliet.md @@ -4,7 +4,7 @@ - Header: `Juliet\include\Juliet.h` ## AI Description -This header defines platform-specific macros, including conditional Windows support and debug features. It implements a modular design for optional ImGui disabling while ensuring strict Win32 compatibility through export definitions and runtime configuration flags. +The `Juliet.h` header file serves as the primary interface for defining basic includes and macros in a C++ project. It includes conditional compilation directives to support Windows-specific features and provides macros for debugging and disabling ImGui, which is a popular cross-platform GUI library. The use of `#pragma once` ensures that the header file is included only once per compilation unit, optimizing performance. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_HAL_Display_Win32_Win32DisplayDevice.md b/Romeo/docs/Juliet_src_Core_HAL_Display_Win32_Win32DisplayDevice.md index a11a70a..5b928b0 100644 --- a/Romeo/docs/Juliet_src_Core_HAL_Display_Win32_Win32DisplayDevice.md +++ b/Romeo/docs/Juliet_src_Core_HAL_Display_Win32_Win32DisplayDevice.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\Core\HAL\Display\Win32\Win32DisplayDevice.cpp` ## AI Description -The Win32DisplayDevice component manages Windows display operations using the Win32 API, handling window creation, destruction, event pumping, and title management within the Juliet framework. It serves as a factory-registered implementation that provides hardware access for platform-specific rendering tasks. +The `Win32DisplayDevice` class is a concrete implementation of the `DisplayDevice` interface in the Juliet framework, designed to manage display-related functionalities on Windows. It encapsulates the necessary components for creating and managing windows that represent the display devices. The class provides methods such as initializing, shutting down, freeing resources, creating platform-specific windows, and handling window events. The factory function `Win32DisplayDeviceFactory` is used to create instances of this device, which can be registered with the framework to handle display-related tasks. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_HAL_Display_Win32_Win32DisplayEvent.md b/Romeo/docs/Juliet_src_Core_HAL_Display_Win32_Win32DisplayEvent.md index 2c7ef7f..917573b 100644 --- a/Romeo/docs/Juliet_src_Core_HAL_Display_Win32_Win32DisplayEvent.md +++ b/Romeo/docs/Juliet_src_Core_HAL_Display_Win32_Win32DisplayEvent.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\HAL\Display\Win32\Win32DisplayEvent.cpp` ## AI Description -This C++ component manages Windows event handling for display interaction within the Juliet framework. It translates Win32 messages into high-level events like keystrokes and mouse motions while supporting IMGUI integration via a custom window procedure callback that forwards user input to the core system without manual polling limitations. +The `Win32DisplayEvent` class in the provided C++ component is designed to manage and dispatch events for a Windows-based display device. It includes functions to pump messages from the operating system, process keyboard and mouse input, and handle window-related events such as close requests and mouse movements. The class utilizes the Win32 API to interact with the operating system's message queue and event handling mechanisms. The `PumpEvents` function is responsible for polling the message queue and dispatching them to appropriate handlers, while the `Win32MainWindowCallback` function processes messages specific to the main window of the display device. This component is crucial for managing user interactions and ensuring smooth operation within a Windows-based environment. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_HAL_Display_Win32_Win32Window.md b/Romeo/docs/Juliet_src_Core_HAL_Display_Win32_Win32Window.md index b4f1391..b0d4ba8 100644 --- a/Romeo/docs/Juliet_src_Core_HAL_Display_Win32_Win32Window.md +++ b/Romeo/docs/Juliet_src_Core_HAL_Display_Win32_Win32Window.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\HAL\Display\Win32\Win32Window.cpp` ## AI Description -This header defines the Win32 display platform for the Juliet framework. It provides functions to create, destroy, show, hide, and set titles for windows using native HWND/HDC handles via a lightweight internal state structure inheriting from the base WindowState class. +The `Win32Window` class in the Juliet project is a platform-specific implementation of the `Window` interface for Windows. It provides methods to create, destroy, show, hide, and set the title of windows on the operating system. The class uses Win32 API functions such as `CreateWindowExA`, `ShowWindow`, and `SetWindowTextA` to interact with the window handle. The `SetupWindowState` and `CleanUpWindowState` helper functions manage the lifecycle of the `Window32State` structure, which holds additional state information specific to the Win32 platform. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_HAL_DynLib_Win32_DynamicLibrary.md b/Romeo/docs/Juliet_src_Core_HAL_DynLib_Win32_DynamicLibrary.md index 5ea5ac5..7202242 100644 --- a/Romeo/docs/Juliet_src_Core_HAL_DynLib_Win32_DynamicLibrary.md +++ b/Romeo/docs/Juliet_src_Core_HAL_DynLib_Win32_DynamicLibrary.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\Core\HAL\DynLib\Win32\DynamicLibrary.cpp` ## AI Description -This C++ component implements Windows dynamic library loading via LoadLibraryA and GetProcAddress, with corresponding error logging. It includes functions to load libraries into the execution space by filename or handle pointer, retrieve exported function addresses safely using NonNullPtr wrappers, manage warnings, unload modules via FreeLibrary, provide comprehensive internal validation checks for invalid inputs, and maintain clean object-oriented interface design through reinterpret casts on HMODULE structures while ensuring robust error handling. +The `DynamicLibrary` class in the Juliet project is designed to facilitate dynamic loading of shared libraries on Windows systems. It provides methods for loading a library by its filename, retrieving function pointers from the loaded library, and unloading the library when it's no longer needed. The class uses the Windows API functions `LoadLibraryA`, `GetProcAddress`, and `FreeLibrary` to handle these operations. The `LogManager` is utilized to log any errors that occur during the loading process, ensuring robust error handling in the application. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_HAL_Event_Keyboard.md b/Romeo/docs/Juliet_src_Core_HAL_Event_Keyboard.md index 1fda07f..d095b2e 100644 --- a/Romeo/docs/Juliet_src_Core_HAL_Event_Keyboard.md +++ b/Romeo/docs/Juliet_src_Core_HAL_Event_Keyboard.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\Core\HAL\Event\Keyboard.cpp` ## AI Description -The C++ Keyboard HAL component manages global keyboard input by tracking scan codes and modifier states internally. It processes key press/release events to detect repeats, convert scan codes to logic keys using mappings, update modifier flags like CapsLock or NumLock dynamically, and post standardized system events with precise timestamps for the Juliet framework. +This C++ component is designed to manage keyboard events in a game engine. It includes functions for sending key presses and releases, checking if a specific key is down, retrieving the current state of all keys, and converting scan codes to corresponding key codes based on modifiers. The implementation uses an anonymous namespace to encapsulate the internal workings, ensuring that the code remains clean and modular. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_HAL_Event_KeyboardMapping.md b/Romeo/docs/Juliet_src_Core_HAL_Event_KeyboardMapping.md index fdf94a5..750315c 100644 --- a/Romeo/docs/Juliet_src_Core_HAL_Event_KeyboardMapping.md +++ b/Romeo/docs/Juliet_src_Core_HAL_Event_KeyboardMapping.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\HAL\Event\KeyboardMapping.cpp` ## AI Description -This C++ module provides a default US keyboard mapping service, translating raw scan codes into logical keycodes. It defines static mappings for printable and non-printable keys while handling dynamic state via the Shift modifier and Caps Lock to produce correct character outputs. The component validates input ranges before resolving identifiers. +The `KeyboardMapping.h` header file defines a function `GetKeyCodeFromDefaultMapping` that takes a `ScanCode` and a `KeyModState` as input and returns the corresponding `KeyCode`. The function uses a default US ASCII mapping to convert scan codes into key codes. It handles special keys such as delete, caps lock, F1-F24, and power by returning specific key codes. For other characters that do not convert to ASCII code, it calls `GetNonPrintableKeys` to determine the appropriate key code based on the scan code. The source file `KeyboardMapping.cpp` contains the implementation of these functions, including the default US ASCII mapping and additional logic for handling special keys. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_HAL_Event_Mouse.md b/Romeo/docs/Juliet_src_Core_HAL_Event_Mouse.md index 77ae563..bfb553e 100644 --- a/Romeo/docs/Juliet_src_Core_HAL_Event_Mouse.md +++ b/Romeo/docs/Juliet_src_Core_HAL_Event_Mouse.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\Core\HAL\Event\Mouse.cpp` ## AI Description -This module manages global mouse state and generates internal events for motion, button presses, and releases. It maintains a single shared Mouse instance tracking absolute position within windows and validates coordinates to ensure they stay within valid window bounds before emitting system-level input notifications. +The `Mouse` class in the Juliet project is designed to handle mouse input and events. It provides methods for sending mouse motion, button press/release events, checking if a specific mouse button is pressed, and retrieving the current mouse position. The class uses private member variables to store the state of the mouse, including its position, previous position, and button state. The `SendMouseMotion` function is responsible for updating the mouse state based on the timestamp, window, and mouse ID, while also ensuring that the mouse position stays within the bounds of the window. The class uses a static instance to manage the global mouse state across different parts of the application. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_HAL_Event_WindowEvent.md b/Romeo/docs/Juliet_src_Core_HAL_Event_WindowEvent.md index fdd8541..7cb0ef3 100644 --- a/Romeo/docs/Juliet_src_Core_HAL_Event_WindowEvent.md +++ b/Romeo/docs/Juliet_src_Core_HAL_Event_WindowEvent.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Core\HAL\Event\WindowEvent.cpp` ## AI Description -This component dispatches window-specific events through the system event pipeline. It validates input windows, constructs a standardized SystemEvent with an associated Window ID and type tag, queues it via the HAL add-event mechanism, and returns success or failure status. The design promotes loose coupling between display subsystems and application logic using explicit enumeration-based typing. +The `WindowEvent` class in the Juliet project is designed to facilitate communication between different components of a graphical user interface (GUI) system. It encapsulates information about events related to windows, such as creation, destruction, and changes in state. The class provides a method `SendWindowEvent` that takes a pointer to a `Window` object and an event type as parameters. This method constructs a `SystemEvent` object with the necessary data and adds it to the system's event queue using the `AddEvent` function. The purpose of this component is to ensure that all GUI-related events are handled uniformly and efficiently, facilitating smooth interactions between different parts of the application. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_HAL_Filesystem_Win32_Win32Filesystem.md b/Romeo/docs/Juliet_src_Core_HAL_Filesystem_Win32_Win32Filesystem.md index 4e3b5ac..bdf2658 100644 --- a/Romeo/docs/Juliet_src_Core_HAL_Filesystem_Win32_Win32Filesystem.md +++ b/Romeo/docs/Juliet_src_Core_HAL_Filesystem_Win32_Win32Filesystem.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\Core\HAL\Filesystem\Win32\Win32Filesystem.cpp` ## AI Description -Provides executable path retrieval and absolute path validation for the Juliet Win32 filesystem. Retrieves module filename safely, handles dynamic buffer allocation for long paths by doubling size if needed, then strips directory components to isolate base execution folder while ensuring valid UNC or disk-designator formats are recognized as absolute. +The `GetBasePath` function in the provided C++ code is designed to retrieve the base path of the executable file. It allocates a buffer that can hold the module size and iteratively searches for the backslash character, which marks the end of the base path. The `IsAbsolutePath` function checks if a given string is an absolute path by verifying if it starts with either two backslashes or a disk designator followed by a colon and a backslash. This ensures that the function correctly identifies the base directory of the executable file, regardless of its location in the file system. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_HAL_IO_Win32_Win32IOStream.md b/Romeo/docs/Juliet_src_Core_HAL_IO_Win32_Win32IOStream.md index a53c772..81299eb 100644 --- a/Romeo/docs/Juliet_src_Core_HAL_IO_Win32_Win32IOStream.md +++ b/Romeo/docs/Juliet_src_Core_HAL_IO_Win32_Win32IOStream.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\Core\HAL\IO\Win32\Win32IOStream.cpp` ## AI Description -This C++ component implements a high-performance Win32 file I/O abstraction for the Juliet framework. It provides optimized read/write operations, seeks support, and memory management via an `IOStream` interface using native functions like CreateFileA and ReadFile on Windows systems. +The `Win32IOStream.cpp` file is a C++ implementation of an I/O stream for Windows systems. It provides functionality to read from and write to files, including support for seeking within the file and handling different modes such as reading, writing, appending, and reading/writing in append mode. The class uses the Win32 API to interact with the operating system's file system, ensuring compatibility across various platforms. The implementation includes methods to open a file, read from it, write to it, seek within the file, and close the stream. The `IOFromFile` function is used to create an instance of this I/O stream interface for a given file path and mode, which can be useful in applications that require file I/O operations on Windows systems. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_HAL_OS_Win32_Win32OS.md b/Romeo/docs/Juliet_src_Core_HAL_OS_Win32_Win32OS.md index 06c2778..34d8da9 100644 --- a/Romeo/docs/Juliet_src_Core_HAL_OS_Win32_Win32OS.md +++ b/Romeo/docs/Juliet_src_Core_HAL_OS_Win32_Win32OS.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\Core\HAL\OS\Win32\Win32OS.cpp` ## AI Description -This Win32OS component provides a C++ OS abstraction layer for the Juliet framework. It implements memory management via VirtualAlloc/Free, includes exception handling and instance protection logic, initializes Windows networking functions to access RIO APIs, and registers its function table globally. +This C++ component is designed to provide a high-level interface for interacting with the Windows operating system. It includes functions for memory management, debugging utilities, and handling exceptions. The `OS` class encapsulates these functionalities, providing a clean and efficient way to interact with the underlying operating system APIs. The `Internal` namespace contains implementation details that are not exposed to the public API. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_HotReload_Win32_Win32HotReload.md b/Romeo/docs/Juliet_src_Core_HotReload_Win32_Win32HotReload.md index ae843b3..ee60a7d 100644 --- a/Romeo/docs/Juliet_src_Core_HotReload_Win32_Win32HotReload.md +++ b/Romeo/docs/Juliet_src_Core_HotReload_Win32_Win32HotReload.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\Core\HotReload\Win32\Win32HotReload.cpp` ## AI Description -This component implements Windows-specific hot-reloading logic for DLLs. It copies original DLLs to unique temporary files with atomic IDs and dynamically loads functions from them. The design tracks file modification times to detect updates, manages transient memory via scratch arenas, and supports reloading or unloading based on validity checks within the Juliet namespace architecture. +This C++ component is designed to manage the loading and unloading of DLL files dynamically within a Juliet application. It includes functions to load code from a specified DLL file into memory, handle errors during the process, and provide functionality to check if the loaded code needs to be reloaded based on its last write time. The component uses a transient allocator for temporary memory allocation and ensures that the DLLs are properly unloaded when they are no longer needed. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_Juliet.md b/Romeo/docs/Juliet_src_Core_Juliet.md index 93a2a75..0cc0d4a 100644 --- a/Romeo/docs/Juliet_src_Core_Juliet.md +++ b/Romeo/docs/Juliet_src_Core_Juliet.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\Core\Juliet.cpp` ## AI Description -This C++ component manages the initialization and shutdown of optional Juliet systems like displays using a reference-counting mechanism. It tracks system state via atomic counters to ensure safe lifecycle management, initializing subsystems on demand while preventing premature destruction during startup sequences. +This C++ component, `Juliet`, is designed to manage the initialization and shutdown of various systems within a classified application. It includes functionalities for initializing and shutting down display systems, as well as managing system references and ensuring proper resource management during the lifecycle of the application. The component utilizes a static array `SystemInitRefCount` to track the number of times each system has been initialized, allowing for efficient reference counting and preventing premature shutdowns. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_Math_MathRound.md b/Romeo/docs/Juliet_src_Core_Math_MathRound.md index 32f2769..4e85a56 100644 --- a/Romeo/docs/Juliet_src_Core_Math_MathRound.md +++ b/Romeo/docs/Juliet_src_Core_Math_MathRound.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\Core\Math\MathRound.cpp` ## AI Description -This C++ component provides a highly precise, single-precision floating-point rounding function that manipulates IEEE 754 bit patterns for optimal performance. It adapts to different float evaluation modes using consteval and avoids compiler optimizations by employing ForceEval alongside union reinterpretation of bits for exact arithmetic control. +The `MathRound.cpp` file in the Juliet project is a C++ implementation of the `RoundF` function, which rounds a floating-point number to the nearest integer. The function uses bitwise operations and arithmetic to achieve this rounding without using built-in functions like `std::round`. It handles special cases such as NaN (Not-a-Number), infinity, and zero separately. The `GetEps` function calculates the smallest positive floating-point number that is greater than or equal to 1, which is used in the rounding process. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_Memory_MemoryArenaTests.md b/Romeo/docs/Juliet_src_Core_Memory_MemoryArenaTests.md index 92e85d8..6e9e294 100644 --- a/Romeo/docs/Juliet_src_Core_Memory_MemoryArenaTests.md +++ b/Romeo/docs/Juliet_src_Core_Memory_MemoryArenaTests.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\Core\Memory\MemoryArenaTests.cpp` ## AI Description -This file contains unit tests for the C++ MemoryArena component, verifying its allocation of structured data and raw arrays. It checks core behaviors including arena position tracking, clearing, commit sizing policies based on reserved memory blocks, dynamic reallocation (growth/shrink), boundary management via `AllowRealloc`, and protection against buffer overflow during shrinking operations. +The `MemoryArenaTests.cpp` file is a test suite for the `MemoryArena` class in the Juliet project, designed to verify its functionality and performance. It includes various scenarios such as allocating and deallocating memory blocks, pushing structures into arenas, testing commit and reserve operations, and handling reallocation with buffer overflow checks. The tests ensure that the arena behaves correctly under different conditions, including managing memory efficiently and avoiding potential issues related to memory corruption. ## Symbols diff --git a/Romeo/docs/Juliet_src_Core_Networking_Win32_Win32SocketPlatformImpl.md b/Romeo/docs/Juliet_src_Core_Networking_Win32_Win32SocketPlatformImpl.md index 7cf08eb..9990a74 100644 --- a/Romeo/docs/Juliet_src_Core_Networking_Win32_Win32SocketPlatformImpl.md +++ b/Romeo/docs/Juliet_src_Core_Networking_Win32_Win32SocketPlatformImpl.md @@ -4,7 +4,21 @@ - Source: `Juliet\src\Core\Networking\Win32\Win32SocketPlatformImpl.cpp` ## AI Description -The file implements Windows-specific socket functionality using Win32 APIs, including address conversion and error handling via WSAError codes. It utilizes a singleton `WSAAutoRelease` struct to ensure global initialization of the WinSock library within the process lifecycle through constructor execution on startup and destructor cleanup at exit. +The `Win32SocketPlatformImpl.cpp` file is a C++ implementation of the `SocketPlatformImpl` class, which provides platform-specific functionality for socket operations in the Juliet framework. The primary purpose of this component is to handle low-level socket operations such as creating and managing sockets, connecting to remote servers, sending and receiving data over sockets, and closing sockets. + +The design of this component includes several key functions: + +1. **CreateAddress**: This function takes an IP address and a port number as input and returns a `sockaddr_in` structure that represents the socket address in network byte order. It uses the `htonl` function to convert the host's IPv4 address to network byte order. + +2. **GetInvalidSocketHandle**: This function returns the invalid socket handle value, which is used to indicate that no valid socket has been created yet. + +3. **Close**: This function takes a socket handle as input and closes the socket using the `closesocket` function from the Windows Socket API. + +4. **GetErrorString**: This function retrieves the error string corresponding to the last Winsock2 error code using the `WSAGetLastError` function. It returns a string that describes the error, which can be useful for debugging and logging purposes. + +5. **GetErrorStatus**: This function also retrieves the error status corresponding to the last Winsock2 error code. It returns an enum value of type `Socket::Status`, which indicates whether the operation was successful or if there was an error. + +The `WSAAutoRelease` struct is used to ensure that the WinSock2 DLL is properly initialized and cleaned up when the program exits, preventing potential issues related to socket operations. ## Symbols diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_AgilitySDK_d3dx12_d3dx12_property_format_table.md b/Romeo/docs/Juliet_src_Graphics_D3D12_AgilitySDK_d3dx12_d3dx12_property_format_table.md index 428a39f..0ab3884 100644 --- a/Romeo/docs/Juliet_src_Graphics_D3D12_AgilitySDK_d3dx12_d3dx12_property_format_table.md +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_AgilitySDK_d3dx12_d3dx12_property_format_table.md @@ -5,48 +5,43 @@ - Source: `Juliet\src\Graphics\D3D12\AgilitySDK\d3dx12\d3dx12_property_format_table.cpp` ## AI Description -This code snippet appears to be part of a **DirectX 12 (D3D12) runtime source file**, specifically defining internal data structures used for **format casting** and **property layout analysis**. It looks like it was extracted from `d3d12core.cpp` or similar, where the compiler generates tables to handle format conversions efficiently. +The provided code snippet defines a set of constants for different DXGI (DirectX Graphics Interface) formats, including their properties such as bit depth, sRGB status, alignment requirements, and type level. These constants are used in various parts of the DirectX API to specify the format of data being processed or rendered. -Here is a breakdown of what each section does: +Here's a breakdown of some key points from the code: -### 1. Cast Sets (`YOUR_BC7`, etc.) -These arrays define groups of related formats that can be cast to one another without data conversion (e.g., converting `DXGI_FORMAT_R8G8B8A8_UNORM` to its typeless variant is usually free). -* **Purpose:** They allow the hardware or shader compiler to perform fast pointer arithmetic or register mapping between similar formats. -* **The "Null Terminator":** Every array ends with `{ DXGI_FORMAT_UNKNOWN, ... }`. This acts as a sentinel value (similar to `\0` in C strings) so that when searching for a specific format within this list using loops or binary search algorithms defined elsewhere in the file, the loop knows exactly where the valid data stops. +1. **DXGI_FORMAT**: + - This is the main enumeration that defines all possible DXGI formats. + - Each entry in this enumeration corresponds to a specific pixel format supported by Direct3D. -### 2. Property Layout Table (`s_FormatDetail[]`) -This is the most complex part of your snippet. It defines how individual formats are interpreted by the D3D12 runtime regarding alignment, storage size, and component semantics. +2. **Cast Sets**: + - The `D3DFCS_R10G10B10A2`, `D3DFCS_BC6H`, `D3DFCS_BC7`, and `D3DFCS_AYUV` arrays define different color formats that can be used in the cast set. + - These formats are part of the DirectX 12 API and are used for advanced graphics features. -Each object in `s_FormatDetail` contains: -* **Format Info:** The specific format (e.g., `R32G32B32A32_TYPELESS`). -* **Parent Format:** Which "group" or cast set this belongs to. -* **Default Cast Set ID:** Used for mapping conversions. -* **BitsPerComponent:** How many bits each channel uses (e.g., `32` for float types). -* **Alignment Values (`Width/Height/DepthAlignment`):** Crucial for D12 textures. These determine how the GPU aligns pixel data in memory to optimize bandwidth and SIMD performance. For example, 4x8 alignment is often required for high-precision floats on specific hardware. -* **Flags:** Boolean flags indicating if it uses DX9 Vertex/Index formats (`bDX9...`), Planar format support (like YUV or NV12 which split RGB channels into planes), Float normalization behavior, etc. +3. **Bits Per Component**: + - The `BitsPerComponent` array specifies the number of bits per component in each channel of a format. + - For example, `D3DFCS_R32G32B32A32` has 32 bits per component for each channel. -#### Key Flags Explained in your snippet: -* `D3DFL_STANDARD`: Indicates a standard linear texture layout (no special packing). -* `_FLOAT`, `_UINT`, `_SINT` vs `_TYPELESS`: Defines the actual data type expected when casting from that specific format to a generic "typeless" wrapper. This helps shader compilers determine how many registers are needed for an operation like `Add`. -* **YUV/Planar Formats:** You see entries related to Y410, NV12, etc., where flags like `bPlanar` might be set (though explicitly in the snippet provided is tricky without seeing every flag, usually these have specific width alignments due to interleaving of Luma and Chroma). +4. **Alignment Requirements**: + - The `WidthAlignment`, `HeightAlignment`, and `DepthAlignment` arrays specify the alignment requirements for different dimensions of a format. + - For example, `D3DFCS_R32G32B32A32` has 128 bits per element. -### 3. Truncated Data -The last block starts with: -```cpp - { - DXGI_FORMAT_R32G32B_TYPELESS, // Note: Snippet cuts off here/next line - ... -``` -This indicates the list continues for formats like `R16`, `RG16A8_UNORM` (which is often aliased under typeless prefixes in D3D9 headers), and other internal core formats. +5. **Layout**: + - The `Layout` field specifies the layout of the format in memory. + - For example, `D3DFC_UNKNOWN` indicates that the format is unknown or not specified. -### Contextual Observation -The inclusion of `{ DXGI_FORMAT_UNKNOWN }` at the end of these arrays suggests this code is likely generated or maintained to support **backward compatibility** with DX10/DX11 semantics while ensuring robustness against invalid format lookups in a dynamic environment (like creating shaders on-the-fly). +6. **Type Level**: + - The `TypeLevel` field specifies the type level of the format. + - For example, `D3DFTL_PARTIAL_TYPE` indicates that the format can be used for partial data types. -If you are modifying this for game development, typically: -1. You would not edit these arrays unless working directly on the source of `dxgi_core.h` or the D3D runtime headers (as changing them affects how Windows maps your textures to GPU hardware registers globally). -2. The alignment values (`WidthAlignment`) are highly specific to the **DXGIDirectCompute** implementation for that specific generation; they often dictate whether a texture fits in SRAM, L1 Cache, or requires more expensive memory transactions when accessed via shaders. +7. **Component Name and Interpretation**: + - The `ComponentName` and `ComponentInterpretation` arrays specify the names and interpretations of each channel in a format. + - For example, `R`, `G`, `B`, and `A` are the names of the channels in `D3DFCS_R32G32B32A32`. -Are you trying to understand how format casting works here? Or do you need help calculating alignment requirements based on these flags? +8. **Flags**: + - The `bDX9VertexOrIndexFormat`, `bDX9TextureFormat`, `bFloatNormFormat`, `bPlanar`, `bYUV`, `bDependantFormatCastSet`, and `bInternal` fields specify various properties of the format. + - For example, `D3DFL_CUSTOM` indicates that the format is custom and not part of a standard set. + +This code snippet ## Symbols diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Buffer.md b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Buffer.md new file mode 100644 index 0000000..d30eb38 --- /dev/null +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Buffer.md @@ -0,0 +1,28 @@ +# Juliet\src\Graphics\D3D12\D3D12Buffer + +## Source Files +- Header: `Juliet\src\Graphics\D3D12\D3D12Buffer.h` +- Source: `Juliet\src\Graphics\D3D12\D3D12Buffer.cpp` + +## AI Description +The `D3D12Buffer` class in the provided C++ component is designed to manage DirectX 12 buffers efficiently. It encapsulates various aspects of buffer creation, management, and operations such as mapping, unmapping, copying, and transitioning between states. The class uses a bindless descriptor heap for constant buffers and structured buffers, which allows for efficient resource management and access. The `CreateGraphicsBuffer` function is used to create a base buffer, while the `CreateGraphicsTransferBuffer` function creates transfer buffers for upload and download operations. The `DestroyGraphicsBuffer` function ensures proper cleanup of resources when they are no longer needed. + +## Symbols + +### Namespace `Juliet::D3D12` + +#### Classes, Structs & Unions +- `struct D3D12Buffer` + +#### Functions & Methods +- `extern GraphicsBuffer* CreateGraphicsBuffer(NonNullPtr driver, size_t size, size_t stride, BufferUsage usage, bool isDynamic)` +- `extern void DestroyGraphicsBuffer(NonNullPtr buffer)` +- `extern GraphicsTransferBuffer* CreateGraphicsTransferBuffer(NonNullPtr driver, size_t size, TransferBufferUsage usage)` +- `extern void DestroyGraphicsTransferBuffer(NonNullPtr buffer)` +- `extern void* MapBuffer(NonNullPtr driver, NonNullPtr buffer)` +- `extern void UnmapBuffer(NonNullPtr driver, NonNullPtr buffer)` +- `extern uint32 GetDescriptorIndex(NonNullPtr driver, NonNullPtr buffer)` +- `extern void CopyBuffer(NonNullPtr commandList, NonNullPtr dst, + NonNullPtr src, size_t size, size_t dstOffset, size_t srcOffset)` +- `extern void TransitionBufferToReadable(NonNullPtr commandList, NonNullPtr buffer)` + diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12CommandList.md b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12CommandList.md new file mode 100644 index 0000000..258679a --- /dev/null +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12CommandList.md @@ -0,0 +1,76 @@ +# Juliet\src\Graphics\D3D12\D3D12CommandList + +## Source Files +- Header: `Juliet\src\Graphics\D3D12\D3D12CommandList.h` +- Source: `Juliet\src\Graphics\D3D12\D3D12CommandList.cpp` + +## AI Description +The provided code snippet is a part of a graphics rendering engine, specifically designed for DirectX 12. It includes functions to manage and execute commands in a graphics pipeline. The `ExecuteCommandLists` function is responsible for submitting multiple command lists to the GPU for execution. Here's a breakdown of what this function does: + +### Function Overview +- **Submit Command Lists**: This function takes an array of `NonNullPtr?CommandList?` objects, each representing a command list that needs to be executed. +- **Inflight Fence**: It checks if any of the command lists are currently in flight (i.e., they have been submitted but not yet completed). +- **Signal Fence**: If a command list is not in flight, it signals the fence associated with that command list. This ensures that the GPU will wait for all commands to complete before proceeding. +- **Submit Command List**: It marks the command list as submitted by incrementing a counter and storing the handle of the fence in the `InFlightFences` array. +- **Present Data**: For each present operation, it sets up the swap chain texture container and updates the fence reference count. +- **Cleanups**: It checks for cleanups by comparing the completed value of the fence with the signal value. If they match, it cleanses the command list. +- **Index Buffer**: It sets the index buffer for rendering operations. +- **Push Constants**: It sets push constants for shaders. +- **Descriptor Heaps**: It ensures that descriptor heaps are properly set up before executing commands. + +### Key Points +1. **Fence Management**: The function uses fences to ensure that all commands in a command list are completed before proceeding with the next one. +2. **Resource Barriers**: It handles resource barriers to transition resources between states (e.g., from `GENERIC_READ` to `INDEX_BUFFER`). +3. **Descriptor Heaps**: It ensures that descriptor heaps are properly managed and reused. +4. **Push Constants**: It sets push constants for shaders, which are used in vertex shader stages. + +### Usage +To use this function, you would typically create an instance of `D3D12CommandList`, populate it with commands such as drawing primitives, setting viewports, scissor rectangles, and more, and then call `ExecuteCommandLists` to submit the command list for execution. + +```cpp +// Create a command list +NonNullPtr?CommandList? commandList = Internal::CreateCommandList(d3d12Driver); + +// Populate the command list with commands +Internal::SetViewPort(commandList, viewPort); +Internal::SetIndexBuffer(commandList, indexBuffer, IndexFormat::UInt16, indexCount, offset); + +// Execute the command list +bool success = Internal::ExecuteCommandLists(d3d12Driver, ?commandList); +``` + +This setup ensures that all commands in a command list are executed efficiently and correctly, leveraging DirectX 12's features for efficient resource management and + +## Symbols + +### Namespace `Juliet::D3D12` + +#### Classes, Structs & Unions +- `struct D3D12CommandListBaseData` +- `struct D3D12CopyCommandListData` +- `struct D3D12GraphicsCommandListData` +- `struct D3D12PresentData` +- `struct D3D12CommandList` + +#### Functions & Methods +- `extern CommandList* AcquireCommandList(NonNullPtr driver, QueueType queueType)` +- `extern bool SubmitCommandLists(NonNullPtr commandList)` +- `extern void SetViewPort(NonNullPtr commandList, const GraphicsViewPort& viewPort)` +- `extern void SetScissorRect(NonNullPtr commandList, const Rectangle& rectangle)` +- `extern void SetBlendConstants(NonNullPtr commandList, FColor blendConstants)` +- `extern void SetBlendConstants(NonNullPtr commandList, FColor blendConstants)` +- `extern void SetStencilReference(NonNullPtr commandList, uint8 reference)` +- `extern void SetIndexBuffer(NonNullPtr commandList, NonNullPtr buffer, + IndexFormat format, size_t indexCount, index_t offset)` +- `extern void SetPushConstants(NonNullPtr commandList, ShaderStage stage, uint32 rootParameterIndex, + uint32 numConstants, const void* constants)` + +### Namespace `Juliet::D3D12::Internal` + +#### Functions & Methods +- `extern void SetDescriptorHeaps(NonNullPtr commandList)` +- `extern void DestroyCommandList(NonNullPtr commandList)` +- `extern bool CleanCommandList(NonNullPtr driver, NonNullPtr commandList, bool cancel)` +- `extern void TrackGraphicsPipeline(NonNullPtr commandList, NonNullPtr pipeline)` +- `extern void TrackTexture(NonNullPtr commandList, NonNullPtr texture)` + diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Common.md b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Common.md index 4bc6dd7..c7b0d80 100644 --- a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Common.md +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Common.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Graphics\D3D12\D3D12Common.cpp` ## AI Description -The `Juliet::D3D12` module manages DirectStorage 12 descriptor pools and CPU-side handle indexing. It provides thread-safe mechanisms for allocating, assigning, and releasing resource handles across different heap types (RTV, DSV, SRV) to optimize GPU memory access patterns within the Juliet graphics engine. +The `D3D12StagingDescriptorPool` class in the provided C++ component is designed to manage a pool of staging descriptors for Direct3D 12. It uses an arena-based memory allocator to efficiently allocate and deallocate descriptor handles, ensuring that resources are managed efficiently without fragmentation. The pool supports creating new heaps as needed when the existing ones run out of free descriptors. This class is crucial for transferring data between CPU and GPU in a high-performance graphics application using Direct3D 12. ## Symbols diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12DescriptorHeap.md b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12DescriptorHeap.md index 92b22a7..c1907cf 100644 --- a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12DescriptorHeap.md +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12DescriptorHeap.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Graphics\D3D12\D3D12DescriptorHeap.cpp` ## AI Description -This C++ component manages DirectX 12 descriptor heaps for efficient GPU resource binding. It provides structures and functions to create pools of reusable descriptor stacks, handle allocation from free lists or creation via the driver, and release resources back to memory while tracking usage indices. The design includes internal arena management and type-specific initialization flags like shader visibility to optimize performance in gaming contexts within a larger framework architecture. +This C++ component is designed to manage descriptor heaps in a DirectX 12 graphics environment. It includes functions for creating, destroying, and managing descriptor heaps, including CPU and GPU heaps. The component uses an arena-based memory allocator to efficiently allocate and deallocate descriptors, ensuring that the heap management is both efficient and easy to use. The component also provides functions for acquiring and releasing sampler heaps from a pool, which helps in optimizing resource usage by reusing descriptor heaps. ## Symbols diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12GraphicsDevice.md b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12GraphicsDevice.md index da4f736..e9395c3 100644 --- a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12GraphicsDevice.md +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12GraphicsDevice.md @@ -5,61 +5,30 @@ - Source: `Juliet\src\Graphics\D3D12\D3D12GraphicsDevice.cpp` ## AI Description -Based on the code snippet you provided and its context (likely a framework like **Juliet** or a similar cross-platform DirectX 12 backend), here is an analysis of what this block does. +The provided code snippet is a part of a graphics driver implementation for DirectX 12. It includes functions to initialize and shutdown debugging features for the graphics device. The `InitializeDXGIDebug` function sets up the debug interface for DXGI (DirectX Graphics Infrastructure), while the `InitializeD3D12DebugLayer` function enables the debug layer in D3D12. -### Code Context: Debug Initialization for Windows/Win32 -This section initializes various layers of the Microsoft DX12 debugging infrastructure. It attempts to enable debug capabilities, register callbacks for logging errors, and configure break conditions if something goes wrong (like memory corruption). This usually runs during the driver/device creation phase. +The `OnD3D12DebugInfoMsg` callback function is used to handle debug messages generated by the graphics driver. It logs these messages at different severity levels, such as ERROR and WARNING, using the `LogWarning` function from the `Log` module. -### Key Components Analyzed +Here's a breakdown of the key functions and their functionalities: -#### 1. DXGI Debug Interface (`InitializeDXGIDebug`) -* **Purpose**: Loads the external `dxgidebug.dll` to access low-level graphics debugging interfaces available only on certain Windows versions (Win 10/11). -* **Interfaces Accessed**: - * `IDXGIGetDebugInterface`: Used primarily for getting interface pointers dynamically. - * `IDXGIDebug`: Provides tools like `ReportLiveObjects` to help developers identify leaks or memory usage at runtime. - * `IDXGIInfoQueue`: Manages message queues from the graphics pipeline. -* **Configuration**: It explicitly sets break conditions for **Errors**, **Corruption**, and **Warnings**. This means if a GPU driver error occurs (crash-inducing), the debugger will pause execution to aid investigation. +1. **InitializeDXGIDebug**: + - Loads the DXGI debug DLL. + - Retrieves the IDXGIDebug interface. + - Sets up the break-on-severity for different message severities. + - Reports live objects to the debug interface. -#### 2. D3D12 Debug Layer (`InitializeD3D12DebugLayer`) -* **Purpose**: Enables the official "DirectX 12 Diagnostic Library" debug layer, which adds significant instrumentation overhead but provides detailed trace information about shader compilation and state management. -* **Platform Note**: While often available on Win 10/11, some versions of this function call might fail depending on specific driver configurations or OS builds (indicated by the warning log if it fails). +2. **ShutdownDXGIDebug**: + - Releases the IDXGIDebug interface and the debug DLL. -#### 3. D3D12 Info Queue (`InitializeD3D12DebugInfoQueue`) -* **Purpose**: Configures `ID3D12InfoQueue` to filter which messages are passed up to application logic. -* **Filtering**: It currently only pushes `INFO` severity messages (though the commented-out line suggests `CORRUPTION` was considered but not enabled yet). This prevents log spam while keeping critical info. +3. **InitializeD3D12DebugLayer**: + - Retrieves the ID3D12Debug interface using `D3D12GetDebugInterfaceFunc`. + - Enables the debug layer in D3D12. -#### 4. Message Callback Registration (`OnD3D12DebugInfoMsg`) ? Logger -* **Mechanism**: If using a newer API level (`ID3D12InfoQueue1`), it registers a custom callback `OnD3D12DebugInfoMsg`. -* **Processing Logic**: - * It translates internal Microsoft enum IDs (like `STATE_CREATION`, `CORRUPTION`) into human-readable strings. - * It logs these messages via the framework's logging system (`LogWarning` or `LogError`). - * The logic checks severity: If it is an **ERROR** or **CORRUPTION**, it uses high-priority warnings; otherwise, standard warnings/info. +4. **OnD3D12DebugInfoMsg**: + - Registers a message callback for handling debug messages. + - Logs debug messages at different severity levels. -#### 5. Error Handling ? Cleanup (`ShutdownDXGIDebug`) -* Ensures proper cleanup of loaded DLLs and released COM objects to prevent memory leaks in the debugger itself when shutting down (though this function is defined here, execution happens elsewhere). - -### Potential Issues or Observations in Your Snippet - -1. **Incomplete Line**: The snippet cuts off at `Log(LogLevel::Message, Log`. You likely need to close the statement with a category string and closing parenthesis: - ```cpp - // ... inside InitializeD3D12DebugInfoLogger - driver-?D3D12Device); - } catch (...) { /* handle exception if necessary */ } - Log(LogLevel::Message, LogCategory::Graphics, "Debug info logger initialized"); - #endif - ``` - -2. **Conditional Compilation**: Notice the `#if JULIET_DEBUG` macro. This entire block will be compiled out unless DEBUG is defined. Ensure this flag matches your project's debug settings correctly so runtime checks actually execute. - -3. **Platform Restrictions**: - * `dxgidebug.dll` loading fails on older Windows versions (e.g., Win7) or specific virtualized environments without the necessary graphics stack support. The code handles failure gracefully (`if (FAILED(result))`). - * `ID3D12InfoQueue1` and message callbacks are relatively new; if you target very old GPUs/driver stacks, this might return early silently due to failed queries. - -### How to Use/Verify This Code - -* **To Enable Debugging**: Set the build configuration flag (e.g., `JULIET_DEBUG=TRUE`). -* **Verification**: Run your application under a debugger (WinDbg or Visual Studio) attached while initializing these components. You should see messages printed immediately about loading DLLs and registering callbacks if successful, followed by any warnings/errors generated during D3D12 device creation from the snippets you posted earlier. -* **Testing Crash Recovery**: Trigger a GPU error manually in your app (e.g., access out-of-bounds memory) while this debug layer is active. The application should stop execution and allow inspection via `ReportLiveObjects` if configured correctly with IDXGIDebug, or simply log the corruption message before crashing depending on break settings. +This setup is crucial for debugging issues related to DirectX 12, such as resource management, shader compilation, and execution errors. ## Symbols diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12GraphicsPipeline.md b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12GraphicsPipeline.md index 8080a8b..4ddc009 100644 --- a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12GraphicsPipeline.md +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12GraphicsPipeline.md @@ -5,34 +5,29 @@ - Source: `Juliet\src\Graphics\D3D12\D3D12GraphicsPipeline.cpp` ## AI Description -Based on the code snippet provided, here is a summary of its functionality and analysis: +The provided code snippet is a part of a graphics rendering system, specifically for creating and managing graphics pipelines in a DirectX 12 environment. The `CreateGraphicsPipeline` function takes a `GPUDriver` object and a `GraphicsPipelineCreateInfo` structure as input parameters and returns a pointer to the created `GraphicsPipeline`. This pipeline is responsible for handling vertex and fragment shaders, rasterization, blending, depth/stencil operations, and other rendering states. -### **Purpose** -The primary function defined at the bottom (`GraphicsPipeline::Create`) creates a DirectX 12 Graphics Pipeline State Object (PSO) from high-level rendering states. It acts as an adapter layer, converting Juliet's internal data structures into `D3D12_GRAPHICS_PIPELINE_STATE_DESC` and calling the hardware-accelerated `ID3D12Device::CreateGraphicsPipelineState`. +Here's a breakdown of the key components and functionalities: -### **Key Workflow Steps** -1. **Initialization**: Retrieves D3D12 driver handles (vertex/fragment shaders). Initializes a local structure (`psoDesc`) with shader bytecode pointers and lengths. -2. **Input Conversion**: Converts `VertexInputState` into `INPUT_ELEMENT_DESCs` if attributes exist, defining the layout of vertex data. -3. **Topology ? Primitive Setup**: Sets the primitive topology (e.g., lines, triangles) using mapping tables (`JulietToD3D12_...`). -4. **Helper Calls**: Relies on three conversion helper functions to populate state descriptors: - * `ConvertRasterizerState`: Handles culling, fill mode, etc. - * `ConvertBlendState`: Maps blend factors and write masks for color/alpha channels (supports multiple render targets). - * `ConvertDepthStencilState`: Converts depth comparison and stencil operations (front/back faces). -5. **Multisample Handling**: Calculates sample mask, count, and quality level based on the creation info (`createInfo.MultisampleState`). It sets a standard multi-sampling quality pattern if not manually specified. -6. **Format Conversion**: Translates Juliet's color formats into `D3D12` compatible RTV/DSV formats (handling both depth textures and color render targets). -7. **Root Signature Association**: Uses the driver's pre-compiled "Bindless" root signature to allow flexible state variables in shaders without explicit parameter declaration in vertex structures. -8. **Hardware Creation (`CreateGraphicsPipelineState`)**: The core call that returns an `ID3D12PipelineState`. This is where the actual pipeline logic lives on the GPU side. -9. **Error Handling**: Checks for hardware failures and logs errors to `dual-OS::Log`, cleaning up allocated resources upon failure. +1. **Shader Conversion**: The function converts the provided vertex and fragment shaders from their Juliet shader format to DirectX 12 shader bytecode. This involves copying the shader data and patching it back after overwriting the bytecode if necessary. -### **Code Specifics ? Observations** -* **Mapping Strategy**: Extensive use of helper arrays like `JulietToD3D12_BlendFactor` and mapping functions like `ToUnderlying`. This suggests a design pattern where high-level enums are mapped to D3D's underlying integer/enum values (often 0-7 or specific constants) via tables, allowing the same logic to run across different rendering backends. -* **Independent Blending**: The code checks if there is more than one color target (`if (i ? 0)`), enabling "independent blend enable." This allows two separate sprites to be drawn on top of each other with independent blending settings, which requires the `D3D12_BLEND_ENABLE_INDEPENDENT_blend` flag in D3D12. -* **Sample Quality Heuristic**: The sample quality is set to a default standard if it exceeds single-sample count; otherwise, custom values might be required by specific games (like older PS/DS titles). -* **Unfinished Line**: The snippet cuts off mid-line at the very end (`pipeline-?PrimitiveType = createInfo.`), indicating incomplete logic for copying other pipeline properties or error states. +2. **Rasterizer State**: The rasterizer state is converted from a `GraphicsPipelineCreateInfo` structure to a `D3D12_RASTERIZER_DESC`. This includes settings such as line width, fill mode, depth testing, stencil testing, etc. -### **Potential Improvements / Questions** -1. **Caching**: Does this code handle GPU caching (using `D3DKBCache`)? Currently, it looks like every time a new PSO is requested, the hardware creates a fresh one unless explicitly told otherwise via `CachedPSO`. For modern games with many unique draw calls, explicit caching logic would improve performance. -2. **Static Pipeline States**: Modern D3D12 workflows often move state creation to a separate static pipeline class or function (static PSOs) rather than creating them on-the-fly per scene update if the states don't change between frames. This code seems to be doing dynamic creation, which is simpler but potentially less performant for complex scenes with many variations of blending/rasterization settings per frame in older engines like Juliet's era. +3. **Blend State**: Similar to the rasterizer state, the blend state is converted from a `GraphicsPipelineCreateInfo` structure to a `D3D12_BLEND_STATE`. This involves setting up blending factors, operations, and write masks for different color channels. + +4. **Depth Stencil State**: The depth stencil state is also converted from a `GraphicsPipelineCreateInfo` structure to a `D3D12_DEPTH_STENCIL_DESC`. This includes settings such as depth enable, write mask, depth function, stencil enable, stencil read/write masks, and stencil operations. + +5. **Pipeline Creation**: After converting all the necessary states, the pipeline state is created using the DirectX 12 device's `CreateGraphicsPipelineState` method. The resulting pipeline state is stored in the `GraphicsPipeline` object. + +6. **Vertex Strides**: The function also sets up vertex strides for each vertex buffer description in the `GraphicsPipelineCreateInfo`. This helps in determining how much data to read from each vertex buffer when rendering. + +7. **Primitive Type**: The primitive type of the pipeline is set based on the provided `GraphicsPipelineCreateInfo`. + +8. **Root Signature**: The root signature is bound to the pipeline using the `BindlessRootSignature` object, which likely contains the necessary shader resources and parameters. + +9. **Memory Management**: The function handles memory allocation for the `GraphicsPipeline` object and its associated resources such as shaders, vertex buffers, and render targets. + +This code snippet is crucial for setting up the rendering pipeline in a DirectX 12 application, ensuring that the graphics are rendered correctly according to the specified requirements. ## Symbols diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12InternalTests.md b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12InternalTests.md index df16a9f..cf92e67 100644 --- a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12InternalTests.md +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12InternalTests.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Graphics\D3D12\D3D12InternalTests.cpp` ## AI Description -This C++ component provides D3D12 unit test utilities, including allocation management and descriptor heap testing. Designed exclusively for debug builds via JULIET_DEBUG flags, it isolates verification logic to ensure graphics system integrity without impacting production performance or runtime efficiency. +The `D3D12InternalTests.h` header file serves as a testing framework for the D3D12 graphics device in the Juliet engine. It includes necessary headers and namespaces to facilitate the creation of test cases that validate the functionality of the D3D12 graphics device within the engine. The `D3D12InternalTests.cpp` source file contains the implementation of these tests, ensuring that the D3D12 graphics device operates correctly under various conditions. ## Symbols diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12RenderPass.md b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12RenderPass.md index 4657fdb..fe9e55a 100644 --- a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12RenderPass.md +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12RenderPass.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Graphics\D3D12\D3D12RenderPass.cpp` ## AI Description -The D3D12RenderPass module bridges the Juliet rendering framework with DirectX 12. It initializes render targets and depth states via BeginRenderPass, manages pipeline binding through BindGraphicsPipeline, handles primitive drawing operations, and performs post-render cleanup in EndRenderPass to reset command list resources for reuse. +This C++ component is designed to manage the rendering process in a DirectX 12 graphics application. It provides functions to begin and end a render pass, bind a graphics pipeline, draw primitives, and resolve color textures if necessary. The class encapsulates the logic for setting up the render target, depth stencil, and primitive topology, as well as managing vertex and fragment shaders. The component also handles resource management and synchronization between different stages of the rendering pipeline. ## Symbols diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Shader.md b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Shader.md index 4b90b94..44c5a8e 100644 --- a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Shader.md +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Shader.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Graphics\D3D12\D3D12Shader.cpp` ## AI Description -This D3D12 header defines a structure and factory functions for creating GPU shaders in the Juliet engine. The source allocates memory dynamically to hold shader byte code, returning it as an abstract Shader pointer while managing internal buffer stats like sampler counts within the concrete struct. +The `D3D12Shader` class in the provided C++ component is designed to encapsulate a shader program for use with Direct3D 12. It includes a ByteBuffer to store the shader bytecode and metadata about its components such as samplers, uniform buffers, storage buffers, and storage textures. The class provides methods to create and destroy shader objects, ensuring that memory management and error handling are handled properly. ## Symbols diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12SwapChain.md b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12SwapChain.md index f4ef2e0..90dfa25 100644 --- a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12SwapChain.md +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12SwapChain.md @@ -5,128 +5,61 @@ - Source: `Juliet\src\Graphics\D3D12\D3D12SwapChain.cpp` ## AI Description -Based on the C++ code provided, here is a structured analysis of the D3D12 Swap Chain implementation within what appears to be a game engine or graphics library (likely "Juliet"). +This code snippet is a part of a graphics driver for the Juliet operating system, specifically designed to handle DirectX 12 graphics. It includes functions for creating and managing swapchains, as well as acquiring and releasing textures from these swapchains. -### 1. Core Functionality Summary -The module handles: -* **Swap Chain Creation:** Initializing DXGI swap chains with HDR support options and frame rate control. -* **Texture Management:** Managing the backing D3D12 textures for each back buffer, transitioning states between Presentation (`PRESENT`) and Rendering (`RENDER_TARGET`). -* **Fence Synchronization:** Ensuring previous frames are finished before starting new ones to prevent tearing or accessing dirty buffers during rendering. +Here's a breakdown of what each function does: ---- +### `AcquireSwapChainTexture` -### 2. Detailed Code Analysis by Function +This function is responsible for acquiring a texture from the swapchain. It takes a command list, a window, and a pointer to a texture pointer. The function first checks if there are any pending fences that need to be waited on before acquiring the texture. If so, it waits for those fences. -#### A. State Transition ? Acquisition (`AcquireSwapChainTexture` / `WaitAndAcquire`) -These functions manage the lifecycle of individual back buffer textures. +Then, it creates a presentation barrier to transition the resource state from `D3D12_RESOURCE_STATE_PRESENT` to `D3D12_RESOURCE_STATE_RENDER_TARGET`. After setting up the barrier, it retrieves the swapchain texture container and acquires the active texture. + +Finally, it returns the acquired texture pointer. + +### `WaitAndAcquireSwapChainTexture` + +This function is similar to `AcquireSwapChainTexture`, but it waits for a fence before acquiring the texture. This can be useful in scenarios where you need to ensure that certain operations are completed before proceeding with rendering. + +### `WaitForSwapchain` + +This function waits for the current frame to complete by checking if there are any pending fences. It then returns true if the wait was successful, otherwise false. + +### `GetSwapChainTextureFormat` + +This function retrieves the format of the swapchain texture based on the specified composition and present mode. + +### `Internal::CreateSwapChain` + +This is a private helper function that creates a swapchain for a given window and composition. It initializes the swapchain descriptor, queries the parent factory to make the window association, and then creates the swapchain object. + +### `Internal::DestroySwapChain` + +This is another private helper function that destroys the swapchain and frees all associated resources. + +### Usage + +To use this code, you would typically create a `D3D12Driver` object and pass it to the functions. You would also need to handle the window state and synchronization mechanisms for your application. ```cpp -// ... inside AcquireSwapChainTexture logic -barrierDesc.Type = D3D12_RESOURCE_BARRIER_TYPE_TRANSITION; -barrierDesc.Flags = D3D12_RESOURCE_BARRIER_FLAG_NONE; -barrierDesc.Transition.StateBefore = D3D12_RESOURCE_STATE_PRESENT; // Source state (from GPU) -barrierDesc.Transition.StateAfter = D3D12_RESOURCE_STATE_RENDER_TARGET; // Destination state (for CPU/GPU read/write) +// Create a D3D12 driver instance +auto driver = new Juliet::D3D12Driver(); -// The transition barrier is issued on the command list. -d3d12CommandList-?GraphicsCommandList.CommandList-?ResourceBarrier(1, ?barrierDesc); - -*swapchainTexture = reinterpret_cast?Texture*?(?windowData-?SwapChainTextureContainers[...].ActiveTexture); // Returns a pointer wrapper to access TextureDetails struct directly. -``` -**Key Insight:** The code explicitly transitions the resource from `PRESENT` (owned by DXGI) back to `RENDER_TARGET`. This is standard practice because: -1. Rendering commands (`Draw`, etc.) typically operate on `RENDER_TARGET` or `COPY_SRC/DST` states depending on context, but transitioning immediately allows for faster access without additional fences if the renderer supports it. -2. It prepares the texture to be read by CPU (if using staging buffers) and written to again in subsequent frame passes via copy commands (`ResourceBarrier` with `D3D12_RESOURCE_BARRIER_FLAG_ALLOW_VISUAL_LOSS_DISCARD`). - -#### B. Synchronization Logic (`WaitForSwapchain`) -Before any command list is executed on a new back buffer, this function ensures the previous frame has finished encoding and presenting. - -```cpp -if (windowData-?InFlightFences[windowData-?WindowFrameCounter] != nullptr) { - if (!Wait(d3d12Driver, true, ?windowData-?InFlightFences[...], 1 JULIET_DEBUG_PARAM(...))) return false; +// Create a swapchain for a window +NonNullPtr?Window? window = ...; // Initialize your window object +SwapChainComposition composition = SwapChainComposition::SDR; +PresentMode presentMode = PresentMode::FIFO; +if (!Internal::CreateSwapChain(driver, windowData, composition, presentMode)) +{ + LogError(LogCategory::Graphics, "Failed to create swapchain"); } -return true; -``` -**Key Insight:** This checks the fence associated with the specific frame being processed. If a fence exists (meaning previous work is pending), it waits for that fence to signal completion before proceeding. -#### C. Format Resolution ? Metadata (`GetSwapChainTextureFormat`) -This helper determines the pixel format used by the swap chain, which is crucial for shader compilation and resource generation. - -```cpp -// Returns TextureFormat enum derived from DXGI_FORMAT of active buffer -auto* d3d12Driver = static_cast?D3D12Driver*?(driver.Get()); -return windowData-?SwapChainTextureContainers[windowData-?WindowFrameCounter].Header.CreateInfo.Format; -``` -**Key Insight:** It accesses the `CreateInfo` header stored within the texture container to ensure consistent format handling throughout the engine, rather than querying DXGI directly every time. - -#### D. Swap Chain Creation (`Internal::CreateSwapChain`) -This is the heavy lifter that interfaces with Windows API and DirectX 12 factories. Notable features: - -**1. Configuration:** -* **Resolution:** Uses `0` for width/height, implying full screen usage where the factory determines size based on window client area. -* **Present Mode ? Composition:** Supports SDR (`BG8`) or HDR via a mapping table `SwapchainCompositionToColorSpace`. It dynamically sets color space and format (e.g., RGB10A2 for HDR). -* **Tearing Support:** Checks `driver-?IsTearingSupported` to set the `DXGI_SWAP_CHAIN_FLAG_ALLOW_TEARING` flag if present, preventing frame skips when V-Sync is off. - -**2. Factory Interactions ? WMA (Windows Meta Association):** -```cpp -// Queries for IDXGISwapChain3 interface needed for HDR settings and specific behaviors. -IDXGISwapChain3* swapChain3 = nullptr; -... -swapChain-?QueryInterface(IID_IDXGISwapChain3, ...); // Note: The original CreateSwapChainForHwnd returns a 1 pointer usually, but here it queries then releases the old one? -// Correction in logic analysis: The code does 'query', assigns to swapChain3 variable, and calls Release on swapChain immediately. This implies swapChain returned by QueryInterface was temporary or they are managing two pointers (original + queried) briefly before swapping roles. - -if (!parentFactory-?MakeWindowAssociation(windowHandle, DXGI_MWA_NO_WINDOW_CHANGES)) - Log(LogLevel::Warning, ... "Cannot handle window resizing"); // IMPORTANT: Disables automatic resize messages to D3D12 logic? -``` - -**Key Insight on WMA:** The code calls `DXGI_MWA_NO_WINDOW_CHANGES`. This tells the system **not** to send a `WM_SIZE` message when the user resizes or moves the window. -* *Why?* If the app handles resizing by simply calling `Resize` functions internally without checking Win32 events, this is an optimization (avoiding extra logic). However, if dynamic re-resizing is needed externally, this needs to be reconsidered based on how else size changes are handled in your engine. - -**3. HDR Setup:** -It specifically sets the color space only for `SwapChainComposition::HDR` or other non-SDR types: -```cpp -if (composition != SwapChainComposition::SDR) { - swapChain3-?SetColorSpace1(SwapchainCompositionToColorSpace[...]); -} -``` - ---- - -### 3. Critical Logic Check ? Observations - -#### 🚨 Potential Issue in `CreateSwapChain` Interface Handling -There is a slight logical flow quirk regarding the Swap Chain pointer assignment: - -```cpp -IDXGISwapChain1* swapChain = nullptr; -// Creates chain, returns as IDXGISwapChain1 (or higher if capabilities met) -HRESULT result = driver-?DXGIFactory-?CreateSwapChainForHwnd(..., ?swapChain); - -// Queries for the specific interface immediately after creation -result = swapChain-?QueryInterface(IID_IDXGISwapChain3, reinterpret_cast?void**?(?swapChain3)); -swapChain-?Release(); // ?--- Releases the original pointer passed by reference? -if (FAILED(result)) { ... } -``` -* **Behavior:** `CreateSwapChainForHwnd` creates an interface and returns it. The caller is expected to release *one* copy of that interface eventually. By calling `QueryInterface`, you create a new handle (`swapChain3`). If the original return value from Create doesn't support QueryInterface directly (unlikely) or if memory management isn't strict, releasing via Release() on the temporary variable might be premature depending on D3D12 ownership rules here. -* **Standard Pattern:** Usually: `Create...(?SwapChain)`, then use it until done with all interfaces required for HDR/Feature queries before doing cleanup logic in other parts of your engine's destroy sequence (like `DestroySwapChain`). - -#### 🚨 Memory Management ? Cleanup (`Internal::DestroySwapChain`) -The destructor releases staging resources and frees D3D12 texture objects manually. This indicates a custom resource pool system rather than just relying on DXGI to clean up everything at shutdown, which is good for performance profiling but requires careful `Free` implementations (likely global Free lists common in Rust/Juliet ecosystems). - -#### 📝 Resource Barrier Nuance -In the transition block: -```cpp -barrierDesc.Transition.pResource = ...; // Pointer math looks correct based on struct layout. -barrierDesc.Transition.Subresource = 0; -// Note: Since this is not a multi-sub-resource texture (like video textures), Subresource=0 covers everything. -``` - -### 4. Recommendations / Improvements - -1. **Validate WMA Logic:** Ensure `DXGI_MWA_NO_WINDOW_CHANGES` doesn't break dynamic resolution support in your game engine. If the window moves/resizes but you don't update texture dimensions, it could cause black screens or crashes upon resize. -2. **Interface Management:** The immediate release of the original Swap Chain pointer after acquiring `IDXGISwapChain3` looks unusual if the engine expects to keep using generic features later without re-acquisition every time (e.g., in a destructor). Consider storing the generic interface and only converting up/down when HDR is specifically accessed or during teardown. -3. **Error Handling:** The `CreateSwapChainForHwnd` call checks for failure, but if it fails due to invalid window handle (`IsWindow` check passed earlier), ensure robust logging regarding *why* (e.g., focus lost, incompatible OS version). - -### Conclusion -This is a well-structured implementation of D3D12 Swap Chain logic tailored for an engine that likely supports HDR and custom resolution scaling. The explicit fence waiting and manual state transitions indicate high control over the rendering pipeline to ensure frame timing consistency and prevent visual +// Acquire a texture from the swapchain +NonNullPtr?CommandList? commandList = ...; // Initialize your command list object +Texture* swapChainTexture; +if (!AcquireSwapChainTexture(commandList, window, ?swapChainTexture)) +{ + LogError(LogCategory::Graphics, "Failed ## Symbols diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Synchronization.md b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Synchronization.md index d362373..31d4de7 100644 --- a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Synchronization.md +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Synchronization.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Graphics\D3D12\D3D12Synchronization.cpp` ## AI Description -*No AI description generated yet.* +This C++ component provides synchronization primitives for managing GPU operations in a DirectX 12 environment. It includes functions to wait until the GPU is idle, wait for multiple fences, query fence values, and release fences. The implementation uses a pool of available fences to efficiently manage resources and ensure that commands are executed on the correct GPU. ## Symbols diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Texture.md b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Texture.md index 6e80a82..adc827a 100644 --- a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Texture.md +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Texture.md @@ -5,147 +5,52 @@ - Source: `Juliet\src\Graphics\D3D12\D3D12Texture.cpp` ## AI Description -Based on the code snippet provided and the truncation at the end (`Te`), here is the completed function `TextureTransitionToDefaultUsage`: +It looks like you're working with a graphics library that handles DirectX 12 resources, specifically textures. The code snippet provided is part of a class `TextureManager` within this library, which manages the creation and management of textures in a game engine. + +Here's a breakdown of what the code does: + +### Texture Management + +1. **Texture Formats**: + - The `JulietToD3D12_DepthFormat` array maps Juliet texture formats to their corresponding D3D12 depth formats. + - The `ComputeSubresourceIndex` function calculates the index of a subresource within a texture. + +2. **Resource States**: + - The `GetDefaultTextureResourceState` function determines the default resource state based on the usage flags of the texture. + - The `PrepareTextureSubresourceForWrite` function prepares a texture subresource for writing by transitioning it from its default state to the new specified state. + +3. **Fetching Subresources**: + - The `FetchTextureSubresource` function retrieves a specific subresource from a texture container. + +4. **Resource Barriers**: + - The `TextureSubresourceBarrier` function applies a resource barrier to transition between different resource states. + - The `TextureSubresourceTransitionFromDefaultUsage` and `TextureSubresourceTransitionToDefaultUsage` functions handle the transition of individual subresources or entire textures from their default state. + +### Usage + +- **Prepare Texture Subresource for Write**: This function prepares a texture subresource for writing by transitioning it to the specified usage state. +- **Fetch Texture Subresource**: This function retrieves a specific subresource from a texture container. +- **Texture Subresource Barrier**: This function applies a resource barrier to transition between different resource states. + +### Example Usage + +Here's an example of how you might use these functions in a game engine: ```cpp - void TextureTransitionToDefaultUsage(NonNullPtr?D3D12CommandList? commandList, NonNullPtr?D3D12Texture? texture, - D3D12_RESOURCE_STATES fromTextureUsage) - { - for (uint32 i = 0; i ? texture-?SubresourceCount; ++i) - { - TextureSubresourceTransitionFromDefaultUsage(commandList, ?texture-?Subresources[i], toTextureUsage); // Correction needed based on context logic below - - // However, looking at the name "ToDefault" and the pattern used in other functions (e.g., TextureTransitionToDefaultUsage usually implies going TO default), - // BUT wait: The parameter is `fromTextureUsage`. - // Let's re-evaluate the function signature vs implementation. - - // Signature: ... fromTextureUsage) - // Logic needed: Barrier FROM 'from' TO 'default'. - } - } +NonNullPtr?D3D12CommandList? commandList = ...; // Get the command list +NonNullPtr?D3D12TextureContainer? container = ...; // Get the texture container - }; // namespace Internal -} // namespace Juliet +// Prepare a texture subresource for writing +NonNullPtr?D3D12TextureSubresource? subresource = Internal::PrepareTextureSubresourceForWrite(commandList, container, 0, 0, true, D3D12_RESOURCE_STATE_RENDER_TARGET); + +// Fetch a specific subresource from the texture container +NonNullPtr?D3D12TextureSubresource? fetchedSubresource = Internal::FetchTextureSubresource(container, 0, 0); + +// Apply a resource barrier to transition the subresource to render target state +Internal::TextureSubresourceBarrier(commandList, D3D12_RESOURCE_STATE_RENDER_TARGET, D3D12_RESOURCE_STATE_UNORDERED_ACCESS, fetchedSubresource); ``` -### Analysis ? Correction Context - -Looking closely at `TextureTransitionToDefaultUsage`: -1. **Parameter**: It takes `D3D12_RESOURCE_STATES fromTextureUsage`. This is the state we are currently in and want to leave (transition FROM). -2. **Goal**: The function name implies transitioning TO the "default" usage derived from flags. -3. **Implementation Pattern**: Similar to `TextureSubresourceTransitionFromDefaultUsage` (which goes Default -? New) and `GetDefaultTextureResourceState`. - -**However**, looking at the variable name in your snippet: `TextureSubresourceTransitionToDefaultUsage(..., D3D12_RESOURCE_STATES fromTextureUsage)` -* If you go FROM a specific state TO default, it is named "FromXyz". -* Standard naming conventions usually are "FromState -? ToState". - -Let's look at the function definition `TextureSubresourceTransitionToDefaultUsage`: -It calls: `D3D12_RESOURCE_STATES defaultUsage = GetDefaultTextureResourceState(...)` then barriers. - -**Correction on logic**: -The snippet actually cuts off inside a loop that iterates subresources but does not show what it returns or the call to transition functions. Based on standard graphics API patterns (like Unity/JetLiu style code often found in engines): - -If `TextureTransitionToDefaultUsage` wants to transition **TO** default: -It should take an input state (`from`) and transition **to** the calculated `default`. -* Barrier command: `source = from`, `destination = default`. - -But wait, there is a naming inconsistency in your snippet vs standard logic. Let's look at line 143 of the provided text (implied context): -`void TextureSubresourceTransitionToDefaultUsage(... D3D12_RESOURCE_STATES fromTextureUsage)` -? This looks like it should be **FROM** `fromTextureUsage`, going TO Default? No, usually "Transition To X" means the destination is X. - -Let's assume the function intent: **"Make this texture go back to its default state."** -Therefore: Transition FROM provided argument TO calculated default. - -*Wait*, look at line 148 logic in similar functions often found in this repo (JetLiu/Unity): -There is a pattern mismatch in your snippet if we assume standard naming. -Let's deduce the completion based on `TextureTransitionFromDefaultUsage`: -That one goes: Default -? Specific (Uses `to`). - -So `TextureTransitionToDefaultUsage` likely does: **Specific** (`from`) -? **Default**. -But looking at the parameters again in your snippet: `(D3D12_RESOURCE_STATES fromTextureUsage)` - The variable name suggests it is used as a source for *something else* or maybe the naming is just "From State". - -Actually, let's look at line 148 logic if we assume standard Unity/JetLiu engine code (which this resembles): -`TextureTransitionToDefaultUsage`: Goes FROM `fromState` TO `defaultState`. -The variable name `fromTextureUsage` in the signature is likely misleadingly named as "source", but logically it acts as the source. - -**Let's write the rest of the function assuming:** -```cpp -void TextureTransitionToDefaultUsage(NonNullPtr?D3D12CommandList? commandList, NonNullPtr?D3D12Texture? texture, - D3D12_RESOURCE_STATES fromTextureUsage) // This is likely a typo in my reading, maybe it's 'to'? -// If the goal is "To Default", then: Source = ? Destination = Default. -``` - -**Alternative Interpretation (More Likely for this specific codebase - JetLiu/Unity):** -In many of these engines, there are typos or non-standard naming. Let's look at `TextureSubresourceTransitionFromDefaultUsage` again: -It gets the default state first? No, it takes a target usage and goes TO it (implied by "To" in name but logic might be different). - -Let's re-read line 148 carefully: -```cpp -void TextureSubresourceBarrier(NonNullPtr?D3D12CommandList? commandList, D3D12_RESOURCE_STATES sourceState, - D3D12_RESOURCE_STATES destinationState, ...) { ... } -``` -And `TextureTransitionToDefaultUsage`: -It takes an argument. If we assume standard logic: **Barrier from X to Default**. - -Here is the logical completion for the loop that was cut off at line 158 (`Te`): - -The code inside `TextureTransitionToDefaultUsage` (lines ~147-160) usually looks like this in similar repositories. The variable name provided in your snippet `(D3D12_RESOURCE_STATES fromTextureUsage)` suggests the input state is being treated as the **source**. Since we are transitioning *to* default, that means: -Source = `fromTextureUsage` (the one passed in) -Destination = Calculated Default - -However, there is a very high probability the variable name inside your snippet was intended to be just an argument for "transitioning TO", i.e., `TransitionToDefault(FromState=Current, ToState=None/Unknown -? Calculate Default)`. Wait, if it takes *only one* state parameter, and we know how to calculate default from flags (which are on the texture/container), then that single parameter MUST be the **Source State** (`from`). - -So the completion is: -```cpp - TextureSubresourceBarrier(commandList, - subresources[i].Parent-?Resource -? CurrentState?, // No wait. - subresources[i].Index); -``` -Wait, I need to map this correctly based on `TextureSubresourceTransitionToDefaultUsage` which does the single step loop. - -Let's reconstruct the exact lines missing after `Te`: - -The function `TextureTransitionToDefaultUsage` is the wrapper that loops through all sub-resources and calls a helper for each one with "to-default" logic. -Wait, if there was already a helper `TextureSubresourceTransitionToDefaultUsage`, why loop? -Ah! The snippet shows: -1. `GetDefault...` (calculated from flags) -2. Helper function A: `From Default To New` -3. Helper function B: `From X To Default` - -Wait, look at line 148 logic in your text again: -```cpp -void TextureSubresourceTransitionToDefaultUsage(... D3D12_RESOURCE_STATES fromTextureUsage) // Arg name is FROM? -{ - ... defaultUsage = GetDefault... () // Calculates DEFAULT based on FLAGS. - TextureSubresourceBarrier(commandList, fromTextureUsage, defaultUsage, subresource); // BARRIER: From Arg -? To Default -} -``` -Yes! The argument `fromTextureUsage` IS the source state we are leaving to go back to the flag-based default. - -So the final function loop iterates and calls this helper. - -**Completed Code:** - -```cpp - TextureSubresourceTransitionToDefaultUsage(commandList, ?texture-?Subresources[i], fromTextureUsage); // Call matches argument logic: Transition FROM 'from' TO Default - - return; // Optional if C++ style requires explicit end or just returns void naturally - } - - }; // namespace Internal -} // namespace Juliet (or whatever the outer namespace is) -``` - -**Wait, one final check on your snippet's `Te` line:** -The snippet ends with: `for (uint32 i = 0; i ? texture-?SubresourceCount; ++i); Te`. -It seems to have a typo in the loop structure or it just cut off. Assuming standard indentation and logic, here is the full block you need: - -```cpp - void TextureTransitionToDefaultUsage(NonNullPtr?D3D12CommandList? commandList, NonNullPtr?D3D12Texture? texture, - D3D12_RESOURCE_STATES fromTextureUsage) // Assuming 'from' means source state we are leaving to go to default. Note: If the name meant "Transition TO Default", why take a 'From'? Because you need an entry point unless it's always current? Yes, taking specific input allows forcing transition regardless of internal state). - { - for (uint32 i = 0; i ? texture-?SubresourceCount; ++i) // Complete the loop - { - TextureSubresourceTransitionToDefaultUsage(commandList, ?texture-?Subresources[i], fromTextureUsage +This code snippet demonstrates how to prepare and manage texture resources in a game engine using DirectX 12. ## Symbols diff --git a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Utils.md b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Utils.md index 4a62013..903d5d5 100644 --- a/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Utils.md +++ b/Romeo/docs/Juliet_src_Graphics_D3D12_D3D12Utils.md @@ -5,7 +5,7 @@ - Source: `Juliet\src\Graphics\D3D12\D3D12Utils.cpp` ## AI Description -This C++ component provides utility functions for DirectX 12 error reporting within the Juliet project. Its primary responsibility is logging detailed Windows system and GPU device errors to developers using formatted HRESULT codes and human-readable messages, specifically handling `DXGI_ERROR_DEVICE_REMOVED` scenarios by retrieving specific removal reasons. +The `D3D12Utils.h` header file defines a utility class for handling DirectX 12 errors in C++. It includes functions to log error messages and retrieve the device removed reason when the device is removed. The `LogError` function takes an `ID3D12Device5` pointer, an error message, and an HRESULT result as parameters. It uses the Windows API's `FormatMessageA` function to convert the HRESULT into a human-readable string and logs it using the `LogManager`. If no error message can be retrieved from the system errors, it posts the code instead. The `D3D12Utils.cpp` source file provides the implementation of the `LogError` function, which uses SDLGPU's `FormatMessageA` function to convert the HRESULT into a human-readable string and logs it using the `LogManager`. ## Symbols diff --git a/Romeo/docs/Juliet_src_Graphics_DebugDisplayRenderer.md b/Romeo/docs/Juliet_src_Graphics_DebugDisplayRenderer.md index 94f5310..0dfe666 100644 --- a/Romeo/docs/Juliet_src_Graphics_DebugDisplayRenderer.md +++ b/Romeo/docs/Juliet_src_Graphics_DebugDisplayRenderer.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\Graphics\DebugDisplayRenderer.cpp` ## AI Description -This C++ component renders debug overlays (lines and sphere wireframes) using a shared GPU buffer split into two regions for depth-tested primitives and non-depth overlay data. It manages shader pipeline creation, vertex allocation up to ~450KB, and command rendering with view projection push constants per region within the Juliet graphics framework. +The `DebugDisplayRenderer` class in the provided C++ code is designed to render debug visualizations such as lines and spheres on a graphics device. It manages the creation, initialization, and cleanup of resources required for rendering these debug elements. The component includes functions to add lines and spheres to the debug state, prepare the GPU buffers for rendering, and flush the debug data to the graphics pipeline during rendering passes. The class uses push constants to pass necessary transformation matrices and lighting information to the shaders, ensuring that the debug visualizations are rendered correctly on the screen. ## Symbols diff --git a/Romeo/docs/Juliet_src_UnitTest_Container_VectorUnitTest.md b/Romeo/docs/Juliet_src_UnitTest_Container_VectorUnitTest.md index 65e3f47..528a1e4 100644 --- a/Romeo/docs/Juliet_src_UnitTest_Container_VectorUnitTest.md +++ b/Romeo/docs/Juliet_src_UnitTest_Container_VectorUnitTest.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\UnitTest\Container\VectorUnitTest.cpp` ## AI Description -This C++ header serves as an unconditionally disabled test suite for the Vector class. The source file contains unit tests verifying container state, operations like `PushBack` and removal via swap (`RemoveAtFast`), memory reallocation logic with external arenas, move semantics support, resizing behavior, iteration correctness, and volume performance checks using assertions on size, iterators, element values, and pointer nullification states under various configurations. +This C++ component is designed to test various functionalities of a `VectorArena` class within the Juliet framework. It includes tests for basic operations such as creating, pushing back elements, removing elements using `RemoveAtFast`, clearing and reusing the vector, testing with different types including structs and move semantics, and verifying the behavior under external arena usage and volume constraints. The component uses assertions to ensure that the vector behaves as expected throughout its lifecycle. ## Symbols diff --git a/Romeo/docs/Juliet_src_UnitTest_RunUnitTests.md b/Romeo/docs/Juliet_src_UnitTest_RunUnitTests.md index d5e7e20..9ea4283 100644 --- a/Romeo/docs/Juliet_src_UnitTest_RunUnitTests.md +++ b/Romeo/docs/Juliet_src_UnitTest_RunUnitTests.md @@ -4,7 +4,7 @@ - Source: `Juliet\src\UnitTest\RunUnitTests.cpp` ## AI Description -This header defines a debug-only unit test runner for the Juliet system. Its responsibility is to execute specific validation suites like memory arena and vector checks via two forward-declared functions within the UnitTest namespace, logging execution status through LogManager only when JULIET_DEBUG is enabled at compile time. +The `RunUnitTests` function in the provided C++ component is designed to execute a series of unit tests for the Juliet library. It leverages the `LogManager` and `LogTypes` classes from the Core module to log messages indicating the start and completion of the tests, providing feedback on their execution status. The function calls two specific test functions: `TestMemoryArena` and `VectorUnitTest`, which are responsible for testing memory management and vector operations within the Juliet library, respectively. This approach ensures that the library's functionality is thoroughly tested before release. ## Symbols diff --git a/Romeo/docs/romeo.db b/Romeo/docs/romeo.db index 2f1bc05..2bd6c3f 100644 Binary files a/Romeo/docs/romeo.db and b/Romeo/docs/romeo.db differ diff --git a/Romeo/src/AiGenerator.cpp b/Romeo/src/AiGenerator.cpp index 7276d5e..ffbe4b3 100644 --- a/Romeo/src/AiGenerator.cpp +++ b/Romeo/src/AiGenerator.cpp @@ -170,6 +170,71 @@ namespace Romeo return true; } + static Juliet::String CleanAndFormatDescription(Juliet::Arena* arena, const Juliet::String& rawResponse, bool enableCoT) + { + Assert(arena != nullptr); + if (rawResponse.Size == 0) + { + return {}; + } + + const char* pStr = CStr(rawResponse); + size_t len = rawResponse.Size; + + const char* thinkStart = strstr(pStr, ""); + const char* thinkEnd = thinkStart ? strstr(thinkStart, "") : nullptr; + + Juliet::String thinkContent = {}; + Juliet::String mainContent = {}; + + if (thinkStart && thinkEnd && thinkEnd > thinkStart) + { + const char* thinkTextStart = thinkStart + 7; + size_t thinkLen = static_cast(thinkEnd - thinkTextStart); + thinkContent = { const_cast(thinkTextStart), thinkLen }; + + const char* afterThink = thinkEnd + 8; + size_t remainingLen = len - static_cast(afterThink - pStr); + mainContent = { const_cast(afterThink), remainingLen }; + } + else + { + mainContent = rawResponse; + } + + // Clean mainContent (remove titles, markdown headers, leading quotes/fences) + const char* mPtr = CStr(mainContent); + size_t mLen = mainContent.Size; + + while (mLen > 0 && (*mPtr == ' ' || *mPtr == '\t' || *mPtr == '\r' || *mPtr == '\n' || *mPtr == '#' || *mPtr == '`')) + { + mPtr++; + mLen--; + } + + while (mLen > 0 && (mPtr[mLen - 1] == ' ' || mPtr[mLen - 1] == '\t' || mPtr[mLen - 1] == '\r' || mPtr[mLen - 1] == '\n' || mPtr[mLen - 1] == '`')) + { + mLen--; + } + + if (enableCoT && thinkContent.Size > 0) + { + size_t resultCap = thinkContent.Size + mLen + 256; + char* resultBuf = Juliet::ArenaPushArray(arena, resultCap JULIET_DEBUG_PARAM("CoTFormattedDesc")); + int written = snprintf(resultBuf, resultCap, + "
\nChain of Thought\n\n%.*s\n\n
\n\n%.*s", + static_cast(thinkContent.Size), CStr(thinkContent), + static_cast(mLen), mPtr + ); + return { resultBuf, static_cast(written > 0 ? written : 0) }; + } + + char* resultBuf = Juliet::ArenaPushArray(arena, mLen + 1 JULIET_DEBUG_PARAM("CleanedDesc")); + memcpy(resultBuf, mPtr, mLen); + resultBuf[mLen] = '\0'; + return { resultBuf, mLen }; + } + bool AI_GenerateDescription( Juliet::Arena* arena, FileEntry& entry @@ -186,8 +251,23 @@ namespace Romeo return true; } - // Formulate the prompt - const char* sysPrompt = "You are a technical documentation assistant. Provide a very short, concise, one-paragraph overview (MAXIMUM 50 WORDS) describing the purpose, main responsibilities, and design of this C++ component. Do not include markdown code block styling or titles in your response; return ONLY the description paragraph. If the current description provided below is already good and accurate, please return it exactly as is."; + Juliet::String cotEnv = GetEnvironmentVar(arena, "ROMEO_ENABLE_COT"); + bool enableCoT = (cotEnv.Size > 0 && (cotEnv.Data[0] == '1' || cotEnv.Data[0] == 't' || cotEnv.Data[0] == 'T' || cotEnv.Data[0] == 'y' || cotEnv.Data[0] == 'Y')); + + const char* sysPromptNoCoT = "You are a technical documentation assistant. Provide a single, concise, unified paragraph overview (50-80 words) describing the main purpose and design of this C++ component.\n" + "Rules:\n" + "1. Do NOT split your output by header file or source file.\n" + "2. Do NOT include titles, markdown headers (e.g. # or ##), bullet lists, or code blocks.\n" + "3. Do NOT include tags or reasoning text.\n" + "4. Return ONLY the description paragraph."; + + const char* sysPromptCoT = "You are a technical documentation assistant. Provide a single, concise, unified paragraph overview (50-80 words) describing the main purpose and design of this C++ component.\n" + "Rules:\n" + "1. You may include your reasoning inside ... tags.\n" + "2. Following the reasoning, output ONLY the final description paragraph.\n" + "3. Do NOT split your final output by header file or source file."; + + const char* sysPrompt = enableCoT ? sysPromptCoT : sysPromptNoCoT; size_t promptCap = strlen(sysPrompt) + entry.HeaderPath.Size + headerContent.Size + entry.CppPath.Size + cppContent.Size + entry.Description.Size + 512; char* promptBuf = Juliet::ArenaPushArray(arena, promptCap JULIET_DEBUG_PARAM("PromptBuf")); @@ -229,9 +309,6 @@ namespace Romeo Juliet::String prompt = { promptBuf, static_cast(written > 0 ? written : 0) }; Juliet::String escapedPrompt = Json_EscapeString(arena, prompt); - // Try local Ollama - // Default Host: localhost:11434 - // Default Model: qwen2.5-coder:1.5b Juliet::String host = ConstString("127.0.0.1"); int port = 11434; Juliet::String modelName = GetEnvironmentVar(arena, "ROMEO_LLM_MODEL"); @@ -240,34 +317,35 @@ namespace Romeo modelName = ConstString("qwen2.5-coder:1.5b"); } - // Check / pull model if needed if (!PullOllamaModelIfNeeded(arena, host, port, modelName)) { return false; } - printf("Romeo AI: Querying local Ollama (%.*s) for '%.*s' description...\n", + printf("Romeo AI: Querying local Ollama (%.*s) [CoT: %s] for '%.*s'...\n", static_cast(modelName.Size), CStr(modelName), + enableCoT ? "ON" : "OFF", static_cast(entry.HeaderPath.Size > 0 ? entry.HeaderPath.Size : entry.CppPath.Size), CStr(entry.HeaderPath.Size > 0 ? entry.HeaderPath : entry.CppPath)); - size_t bodyCap = modelName.Size + escapedPrompt.Size + 256; + int maxPredictTokens = enableCoT ? 600 : 300; + size_t bodyCap = modelName.Size + escapedPrompt.Size + 512; char* bodyBuf = Juliet::ArenaPushArray(arena, bodyCap JULIET_DEBUG_PARAM("OllamaBody")); int bodyLen = snprintf(bodyBuf, bodyCap, - "{\"model\":\"%.*s\",\"prompt\":\"%.*s\",\"stream\":false}", + "{\"model\":\"%.*s\",\"prompt\":\"%.*s\",\"stream\":false,\"options\":{\"temperature\":0.2,\"num_predict\":%d}}", static_cast(modelName.Size), CStr(modelName), - static_cast(escapedPrompt.Size), CStr(escapedPrompt) + static_cast(escapedPrompt.Size), CStr(escapedPrompt), + maxPredictTokens ); Juliet::String body = { bodyBuf, static_cast(bodyLen > 0 ? bodyLen : 0) }; - Juliet::String response = {}; bool success = PostWithRetry( arena, host, port, ConstString("/api/generate"), - false, // isHttps + false, body, response ); @@ -280,7 +358,7 @@ namespace Romeo Juliet::String desc = {}; if (Json_Query(root, "response", desc)) { - entry.Description = Juliet::StringCopy(arena, desc); + entry.Description = CleanAndFormatDescription(arena, desc, enableCoT); return true; } }