# Instructions for Agents ## Scope and Standing Priorities These rules apply to all code creation, modification, correction, or refactoring within the project. The educational constraints below take precedence over any incompatible previous conventions. Descriptions of the existing codebase do not constitute permission to reproduce practices that violate these rules. Apply the following priorities, in this order: 1. Meet the requested functional requirements. 2. Comply with the educational and programming constraints in this document. 3. Reuse existing classes, structures, and functionality. 4. Favor simplicity and readability. 5. Maintain a consistent object-oriented architecture. 6. Avoid any unjustified additional complexity. Do not introduce dependencies, abstractions, or features that have not been requested. ## Project and Entry Points Reference information based on the files in `PICTOR/`. - C++17 graphical demonstration application for Windows x64; Visual Studio solution `PICTOR/PICTOR.sln`, project `PICTOR/PICTOR.vcxproj`. - `student.cpp`: functions `initApp(Model&)`, `processEvent(const Event&, Model&)`, and `drawApp(Graphics&, const Model&)`. The demonstration displays text, textures, shapes, and a cursor. - `Model.h`: application state, currently limited to `currentMousePos`. - `G2D/main.cpp`: window creation, event loop, event conversion and dispatching, and on-demand rendering. Pressing Escape or closing the window terminates the application. - `Graphics.h` and `G2D/Graphics.cpp`: drawing interface and primitive implementations; `G2D/wrapperSDL.*`: SDL management, resources, and rendering. The `Graphics.h` interface does not expose SDL types. - `Event.h`, `G2D/Event.cpp`, `G2D/Key.cpp`: events and key translation. `V2.*`: integer coordinates and vector operations; `Color.*`: floating-point RGBA colors ranging from 0 to 1. - `Font.h`: descriptions of the LiberationMono and Tinos fonts; `Tile.h`: tile drawn relative to its parent, with a background, centered text, and a border. ## Coding Conventions to Follow - Use the signatures of the three `student.cpp` functions expected by `G2D/main.cpp`. - Preserve the distinction between pixel coordinates (`height - 1 - y`) and geometric boundaries (`height - y`) in the wrapper: the application's Y-axis points upward from the bottom of the window. Thick outlines use a half-pixel offset. - Interpret `Event.x/y` according to `Event.Type`: position for `MouseMove`, button number in `x` for `MouseDown/MouseUp`, horizontal/vertical wheel increments for `MouseWheel`, and dimensions for `WindowResize`. Click events do not provide the pointer position; it is stored from `MouseMove` events. - The `fillConvexPolyline` and `fillConvexPolygon` filling functions use triangle-fan triangulation: their input must be convex. - SDL resources are owned by `unique_ptr` objects with SDL destructors; images and fonts are cached in `SDLwrapper`. - Compiled source files are explicitly listed in `PICTOR.vcxproj`: add any new `.cpp` file intended for compilation. ## Memory and Resources - Prohibit raw pointers (`T*`) in application code unless strictly required by an external API, particularly SDL3. Restrict their use to API boundaries rather than adopting them throughout the codebase. - Do not use `new`, `delete`, `malloc`, or `free` for memory management. - Prefer automatic-storage-duration objects, RAII resource management, and STL containers, particularly `std::vector`, `std::array`, and `std::map`. Never introduce manual memory management when a simple solution using the STL or automatic objects is sufficient. - If pointers are essential, particularly for inheritance-based polymorphism, use `std::unique_ptr` by default; reserve `std::shared_ptr` for cases where shared ownership is genuinely necessary. - Preserve the cleanup of created SDL resources, particularly the `SDL_Destroy...` calls used by RAII destructors. These calls do not constitute prohibited manual application memory management. ## Educational Scope and Object-Oriented Design - Stay within C++17 and the concepts covered in the course: `struct`, `class`, simple templates, STL containers and algorithms, smart pointers, inheritance, polymorphism, functors, and lambda expressions. - Produce code that a student familiar only with this curriculum can understand: simple, readable, explicit, and educational rather than technically sophisticated. - Do not introduce complex metaprogramming. Avoid obscure features, unnecessary advanced techniques, and complex design patterns when a conventional object-oriented approach is sufficient. - Favor object-oriented programming: group related data and behavior into coherent classes and consistently respect encapsulation. - Explicitly specify `private` and `public` access levels; declare attributes private by default and expose only the necessary methods. - Add getters or setters only when controlled access or modification is justified, not automatically for every attribute. - Use inheritance and polymorphism to represent natural relationships between objects without artificially complicating the architecture. ## Organization and Geometry - Define at most one main class or structure per file. Do not group multiple independent classes together; strictly related auxiliary declarations may remain in the same file. - For classes, prefer separating declarations (`.h` or `.hpp`) from implementations (`.cpp`), using consistent organization and naming. - Always use the existing `V2` type for 2D geometric calculations: consult `PICTOR/V2.h`, reuse its methods and operators, and do not create a competing vector type or duplicate its operations. - `V2` stores integers: retain the conversions required for SDL types and the floating-point coordinates used internally for rendering to respect half-pixel conventions, without turning them into a competing geometry API. ## Parameters, Naming, and Comments - Mark member methods as `const` when they do not modify the object's state. - Prefer `const T&` for objects that are not modified; use a non-const reference only when intentional modification is required. Pass inexpensive simple types (`int`, `float`, `bool`, etc.) by value, without artificial or unnecessary `const` qualifiers. - Use camelCase for variables, attributes, functions, methods, and parameters (`playerPosition`, `movementSpeed`, `updatePosition`, `deltaTime`). For classes and structures, preserve the existing convention and prefer PascalCase when no convention exists. - Do not rename symbols from external libraries, particularly SDL3, or existing elements unless necessary. - Immediately above each new function or method, add a brief comment explaining its purpose and how it works. Keep comments simple, educational, and useful, without merely paraphrasing the function's name. - If declarations and definitions are separated, place this comment above the declaration in the header, unless an existing convention dictates otherwise. Update comments for existing functions when they undergo significant modifications, if necessary. ## Errors, Exceptions, and SDL3 - Do not implement C++ exception handling: do not introduce `try`, `catch`, or `throw`. - Do not add error propagation or error-handling mechanisms, or dedicated abstraction layers. Do not systematically check or handle return codes that only indicate failure. - For SDL3, do not check or handle return values that merely indicate success or failure; do not add error messages, logs, or conditional branches to handle these failures. Use the API directly with lightweight, readable code, respecting its required pointers and handles. - Preserve checks that are essential to application logic or to preventing undefined behavior. Normal event handling, user input processing, and object lifecycle management remain necessary, as does resource cleanup. - These constraints apply to newly written or modified code. Do not unnecessarily remove existing mechanisms in unrelated parts of the project, particularly exceptions, logs, and fallbacks already present in the wrapper. ## Compilation and Resources The project configures MSVC `v145`, the Windows 10 SDK, C++17, `/utf-8`, and warning level 4. Two configurations are available: `Debug|x64` and `Release|x64`. From the project root, in a terminal where MSBuild and these components are available: ```powershell msbuild PICTOR/PICTOR.sln /p:Configuration=Debug /p:Platform=x64 msbuild PICTOR/PICTOR.sln /p:Configuration=Release /p:Platform=x64 ``` - Executable: `PICTOR/BUILD/bin//PICTOR.exe`; intermediate files: `PICTOR/BUILD/obj//`. - `SDL3import/` provides the x64 headers, libraries, and DLLs for SDL3 and SDL3_ttf; the headers indicate versions 3.4.16 and 3.2.2, respectively. - The `CopyAssets` target copies `images/`, `font/`, and the DLLs next to the executable after compilation; it first deletes any images already present in the output directory. - Resource paths are relative to the executable through `SDL_GetBasePath()`, not to the current working directory. Pass the filename to `drawRectWithTexture`; if an image cannot be found, `64_error.png` is used as a fallback. - Fonts are loaded using the naming pattern `-.ttf`. SDL licenses are located in `SDL3import/*/LICENSE.txt`, and font licenses in `font/*-LICENSE.txt`; retain the required notices when redistributing them. - `.vs/` contains local Visual Studio data; `PICTOR.vcxproj.user` notably configures the debugger's `PATH` for the SDL DLLs. ## Available Verification Procedures - No unit test project or formatting tool is defined in the project files. - `PICTOR_SMOKE_TEST`, when present in the environment, causes the application to perform three rendering passes and then exit without waiting for events. For an already compiled Debug executable: ```powershell $env:PICTOR_SMOKE_TEST = '1' & .\PICTOR\BUILD\bin\Debug\PICTOR.exe Remove-Item Env:PICTOR_SMOKE_TEST ``` - This mode verifies startup and the rendering path, without making assertions about the graphical result. - `Graphics::test` contains visual test scenes (outlines, fills, diagonals, boundaries, and pixels); its invocation `G.test(G)` is currently commented out in `student.cpp`. ## Checklist Before Completing a Programming Task Verify the changes made: - No `new`, `delete`, `malloc`, or `free` introduced for memory management; no raw pointers added unless required by an external API. - Smart pointers used when necessary; STL containers and automatic objects preferred; resource cleanup preserved. - Code restricted to the course curriculum; object-oriented design and encapsulation respected. - At most one main class or structure per file; consistent organization. - `V2` reused for 2D geometry, without duplicating its operations. - `const`, constant references, and pass-by-value used appropriately. - Names comply with the conventions; every new function or method has an explanatory comment. - No exception-handling or error-handling mechanisms added; no handling introduced for SDL3 return values that merely indicate failure.