- sys: add CHostViewport to render app state inside an ImGui window (disabled in Retail and Profile)

- sys: route input to the state viewport in viewport coordinates
- sys: draw EqUI, debug overlays and console in the state viewport, ImGui in a separate pass
- render: debug overlay Draw takes color and depth targets
- equi: Render takes color target
- imgui_backend: add IsTextInputActive
- egfman2: render scene in host viewport between model browser and bottom panel
- docs: describe host viewport, add codestyle rule for ConVar and ConCommand placement

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: SoapyMan

docs/codestyle.md

@@ -35,6 +35,9 @@ The reference shows the general layout; where it disagrees with this document, t
   4. the file's own header last.
 - Public interfaces live under `public/` (`I`-prefixed abstract classes); implementations live next
   to their module (`C`-prefixed classes).
+- In `.cpp` files, console variable and command declarations (`DECLARE_CVAR*`, `DECLARE_CMD*`,
+  see `framework_core.md`) go at the top, after the includes and before function code: file-local
+  helpers and other functions are placed below them.
 - Logical sections inside a file are separated with a dashed comment line:
 
   ```cpp

docs/sys_application_overview.md

@@ -11,6 +11,7 @@ input routing, configs and screenshots. An application links `sysLib` (premake p
 | `sys_window.cpp/.h` | Window creation, SDL init, game loop (`sysHostInit`, `sysHostGameLoop`, `sysHostTerminate`) |
 | `sys_host.cpp/.h` | `g_pHost` (`CGameHost`) — systems, frame, video modes, cursor, input events |
 | `sys_state.cpp/.h` | `CAppStateBase`, `eqAppStateMng` — app states |
+| `sys_viewport.cpp/.h` | `CHostViewport` — state rendering inside an ImGui window |
 | `sys_in_console.cpp/.h` | `g_consoleInput` (`CEqConsoleInput`) — developer console, log |
 | `sys_in_joystick.cpp/.h` | `CEqGameControllerSDL` — game controllers |
 | `cfgloader.cpp/.h` | `WriteCfgFile`, `writecfg` |
@@ -102,6 +103,7 @@ A state is one mode of the application (menu, game, editor). Derive from `CAppSt
 | `HandleKeyPress`, `HandleMouseClick`, `HandleMouseMove`, `HandleMouseWheel`, `HandleJoyAxis` | Input not consumed by console / ImGui / EqUI |
 | `GetMouseCursorProperties(visible, centered)` | Cursor visibility and relative (centered) mouse mode |
 | `GetTimescale()` | Time scale for this state's `dt` |
+| `GetViewport()` | `CHostViewport` the state renders to, `nullptr` for the whole window (see [Host viewport](#host-viewport--chostviewport)) |
 
 State management (`eqAppStateMng`):
 
@@ -140,7 +142,9 @@ frame the loop sleeps `sys_sleep` ms (default 1).
 6. Debug overlay with engine statistics (FPS, draw / dispatch counts, GPU and system memory),
    `r_showFPS`, `r_showFPSGraph`. Screenshot (without console / ImGui), then one render pass with
    the debug overlay, input debug drawing, console (`g_consoleInput->EndFrame`) and ImGui
-   (`g_imGuiHost->EndFrame`).
+   (`g_imGuiHost->EndFrame`). With a visible state viewport, EqUI, debug overlays, input debug
+   drawing and the console go to the viewport target, ImGui is drawn in a separate backbuffer pass
+   and the screenshot is taken after it (see [Host viewport](#host-viewport--chostviewport)).
 7. `EndScene`: `g_matSystem->EndFrame()`.
 8. Pending fullscreen toggle, `g_onEndFrame`.
 
@@ -176,6 +180,11 @@ dispatched by `CGameHost`:
 | Touch | binder touch zones |
 | Text input | ImGui → console |
 
+With a visible state viewport (`GetViewport()`), the console, EqUI and the state receive mouse
+buttons, movement and wheel only over the viewport, in viewport coordinates. Keys and text go past
+the ImGui check while the viewport window is focused or the console is open, unless an ImGui text
+field is active. See [Host viewport](#host-viewport--chostviewport).
+
 Keyboard keys and mouse buttons reach command bindings only if the state forwards them to
 `g_inputCommandBinder->OnPressEvent` (see [input_overview.md](input_overview.md)). Input is ignored
 for 0.25 s after the window regains focus.
@@ -185,6 +194,56 @@ item is hovered, active or focused, or ImGui wants the mouse / keyboard
 (`g_imGuiHost->IsImGuiItemsInFocus()`), the event goes no further; key releases still reach the
 console so its modifier state does not stick.
 
+## Host viewport — `CHostViewport`
+
+A state can render into a render target shown in an ImGui window instead of the whole window
+(tools with panels around the scene). The state owns a `CHostViewport` and returns it from
+`CAppStateBase::GetViewport()`.
+
+```cpp
+CHostViewport m_viewport{ "egfman2_scene" };
+
+CHostViewport* GetViewport() override { return &m_viewport; }
+
+// ImGui handler (runs in BeginScene, before Update)
+if (ImGui::Begin("Scene"))
+	m_viewport.DrawImGui();	// fills the available content region
+ImGui::End();
+
+// Update
+const IVector2D viewSize = m_viewport.GetSize();
+projMat = perspectiveMatrixY(fov, viewSize.x, viewSize.y, zNear, zFar);
+g_renderAPI->BeginRenderPass(
+	Builder<RenderPassDesc>()
+	.ColorTarget(m_viewport.GetColorTarget(), true, clearColor)
+	.DepthStencilTarget(m_viewport.GetDepthTarget())
+	.DepthClear()
+	.End());
+```
+
+- `DrawImGui(size)` resizes the color and depth targets (backbuffer formats, `ResizeRenderTarget`)
+  to the drawn size and puts an invisible button with the image in the current ImGui window. The
+  viewport is *visible* only in a frame where `DrawImGui` was called.
+- Viewports are disabled in `Retail` and `Profile` builds (`HOST_VIEWPORT_ENABLED` in
+  `sys_viewport.h`): `DrawImGui` does nothing and the viewport is never visible.
+- When the viewport is not visible (ImGui window closed, `Retail` or `Profile` build),
+  `GetColorTarget`, `GetDepthTarget` and `GetSize` return the backbuffer, the default depth buffer
+  and the window size, and the host routes input as without a viewport.
+- Input: mouse coordinates passed to the state handlers are relative to the viewport. A button
+  pressed over the viewport captures the mouse until all captured buttons are released, so drags
+  continue outside the viewport. Mouse movement and wheel reach the state while the mouse is over
+  the viewport or captured. Key releases always reach the state, so keys do not stick when focus
+  moves away.
+- `CGameHost::SetCursorPosition` takes viewport coordinates, and a centered cursor
+  (`GetMouseCursorProperties`) is warped to the viewport center.
+- `GetScreenRect`, `ToViewport`, `ToWindow` convert between window and viewport coordinates.
+- The state viewport is the main viewport: the host draws EqUI (`equi::Manager->Render(target)`,
+  view frame of the viewport size), debug overlays (`debugoverlay->Draw` with the viewport targets),
+  `r_showFPS`, input debug drawing and the console only into it. ImGui stays in the window
+  backbuffer. Full-screen edge AA is skipped: its luma pass needs a storage source texture.
+- `screenshot` with a visible viewport saves the whole window with ImGui, since the viewport gets
+  to the backbuffer only through ImGui.
+
 ## Developer console — `g_consoleInput`
 
 - Opened by the key bound to `toggleconsole` (`bind GRAVE toggleconsole` in

docs/tools_overview.md

@@ -55,6 +55,10 @@ skeleton, animations and sequences, physics objects. Built on `sysLib` with an I
 come from `nfd` (`src_dependency/nfd`).
 
 - `-model <path>` opens a model on start.
+- The scene is rendered into a `CHostViewport` (see
+  [sys_application_overview.md](sys_application_overview.md)) shown in the ImGui window between the
+  model browser and the bottom panel; camera and drag input and hotkeys work while the mouse is over
+  the scene or the scene window is focused.
 - Model browser on the left (View → Model browser) lists `.egf` files under `models/` of the `SP_MOD`
   search paths; clicking a file opens it. Directories are scanned when first expanded, Refresh
   rescans them. The filter field shows a flat list of files whose names contain the text (case
@@ -63,13 +67,13 @@ come from `nfd` (`src_dependency/nfd`).
   waits for them. Their stdout and stderr go to the engine console through a pipe (no console window
   is opened); a single compiled model is opened afterwards.
 - Camera: Shift + left / right / middle mouse button drag rotates, zooms and pans; the cursor wraps
-  around the window edges while the camera moves. Left button drag pulls physics objects while
+  around the scene viewport edges while the camera moves. Left button drag pulls physics objects while
   physics simulation runs.
 - Physics preview runs eqPhysics with a fixed 1/60 s step on a floor box at zero height. All
   surface params of the model fall back to one built-in `default` param. Ragdolls
   (`ragdoll/physics_ragdoll.*`) use point and angular limit constraints with the joint limits
   from the `.pod`; ragdoll parts collide only with the floor.
-- Hotkeys: Ctrl+O open, R reset view, P physics objects, B bones, W wireframe.
+- Hotkeys (scene window focused): Ctrl+O open, R reset view, P physics objects, B bones, W wireframe.
 - Writes its ConVars to `cfg/egfman2.cfg` instead of the game `cfg/user.cfg` unless `-user_cfg` is
   given.
 

public/render/IDebugOverlay.h

@@ -23,6 +23,7 @@
 
 class IEqFont;
 class IGPURenderPassRecorder;
+class ITexture;
 
 using OnDebugDrawFn = EqFunction<bool(IGPURenderPassRecorder* rendPassRecorder)>;
 
@@ -306,7 +307,8 @@ class IDebugOverlay
 	virtual void		Graph_AddValue( DDGraphBucket* pBucket, float value) = 0;
 
 	virtual void		SetMatrices( const Matrix4x4 &proj, const Matrix4x4 &view ) = 0;
-	virtual void		Draw(int winWide, int winTall, float timeScale = 1.0f) = 0;
+	// targets are the backbuffer and the default depth buffer when not set
+	virtual void		Draw(int winWide, int winTall, float timeScale = 1.0f, ITexture* colorTarget = nullptr, ITexture* depthTarget = nullptr) = 0;
 
 	// Old interfaces for compatibility
 

shared/equi/EqUI_Manager.cpp

@@ -243,16 +243,16 @@ bool CUIManager::IsWindowsVisible() const
 	return false;
 }
 
-void CUIManager::Render()
+void CUIManager::Render(ITexture* colorTarget)
 {
-	PROF_EVENT("EqUI render");
-
-	if(!m_rootPanel)
+	if (!m_rootPanel || !colorTarget)
 		return;
 
+	PROF_EVENT("EqUI render");
+
 	IGPURenderPassRecorderPtr rendPassRecorder = g_renderAPI->BeginRenderPass(
 		Builder<RenderPassDesc>()
-		.ColorTarget(g_matSystem->GetCurrentBackbuffer())
+		.ColorTarget(colorTarget)
 		.End()
 	);
 	rendPassRecorder->DbgPushGroup("EqUI");

shared/equi/EqUI_Manager.h

@@ -12,6 +12,7 @@
 class IEqFont;
 class IMaterial;
 class IGPURenderPassRecorder;
+class ITexture;
 
 namespace equi
 {
@@ -62,7 +63,8 @@ class CUIManager
 
 	bool				IsWindowsVisible() const;
 
-	void				Render();
+	// renders to the backbuffer when target is not set
+	void				Render(ITexture* colorTarget);
 
 	bool				ProcessMouseEvents(float x, float y, int nMouseButtons, int flags);
 	bool				ProcessKeyboardEvents(int nKeyButtons, int flags);

shared/imgui_backend/imgui_host.cpp

@@ -289,6 +289,16 @@ bool CEqImGuiHost::IsImGuiItemsInFocus() const
 	return false;
 }
 
+bool CEqImGuiHost::IsTextInputActive() const
+{
+#ifdef IMGUI_ENABLED
+	if (!GImGui)
+		return false;
+	return ImGui::GetIO().WantTextInput;
+#endif
+	return false;
+}
+
 void CEqImGuiHost::AddDebugHandler(const char* name, IMGUI_HANDLER func)
 {
 #ifdef IMGUI_ENABLED

shared/imgui_backend/imgui_host.h

@@ -46,6 +46,7 @@ class CEqImGuiHost
 	void			RemoveDebugHandler(const char* name);
 
 	bool			IsImGuiItemsInFocus() const;
+	bool			IsTextInputActive() const;
 
 private:
 	struct Menu

shared/render/DebugOverlay.cpp

@@ -1154,15 +1154,18 @@ void CDebugOverlay::SetMatrices( const Matrix4x4 &proj, const Matrix4x4 &view )
 #endif // ENABLE_DEBUG_DRAWING_PROFILE
 }
 
-void CDebugOverlay::Draw(int winWide, int winTall, float timescale)
+void CDebugOverlay::Draw(int winWide, int winTall, float timescale, ITexture* colorTarget, ITexture* depthTarget)
 {
 	m_frameTime = m_timer.GetTime(true) * timescale;
 
 #ifdef ENABLE_DEBUG_DRAWING_PROFILE
+	if (!colorTarget)
+		return;
+
 	IGPURenderPassRecorderPtr rendPassRecorder = g_renderAPI->BeginRenderPass(
 		Builder<RenderPassDesc>()
-		.ColorTarget(g_matSystem->GetCurrentBackbuffer())
-		.DepthStencilTarget(g_matSystem->GetDefaultDepthBuffer())
+		.ColorTarget(colorTarget)
+		.DepthStencilTarget(depthTarget)
 		.End()
 	);
 

shared/render/DebugOverlay.h

@@ -60,7 +60,7 @@ class CDebugOverlay : public IDebugOverlay
 	void							Graph_AddValue(DDGraphBucket* pBucket, float value);
 
 	void							SetMatrices(const Matrix4x4& proj, const Matrix4x4& view);
-	void							Draw(int winWide, int winTall, float timescale = 1.0f);
+	void							Draw(int winWide, int winTall, float timescale = 1.0f, ITexture* colorTarget = nullptr, ITexture* depthTarget = nullptr);
 
 	static void						OnShowTextureChanged(ConVar* pVar, char const* pszOldValue);
 private: