admin/UE5-Modular-Game-Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0a2d08b2ad2c3ff7e7c1a82cff5fbbe3eb389ed4
UE5-Modular-Game-Framework/docs/blueprints/17-capture/136_BPC_PlanarCapture.md
Lefteris Notas 0a2d08b2ad Add Planar Capture System implementation checklist and developer reference 
- Created a comprehensive implementation checklist for the Planar Capture System (Systems 136-147) detailing tasks across multiple phases including C++ core, material foundation, Blueprint actors, data assets, integration, and performance testing.
- Added a developer reference document outlining the architecture, data flow, state machine, budget enforcement, render target pooling, horror features, integration points, multiplayer networking, performance characteristics, debugging methods, and build order for the capture systems.
- Introduced examples of capture surface usage in the Project Void horror game, including specific implementations for mirrors, monitors, portals, and fake windows, along with a checklist for integration tasks.
2026-05-22 15:36:08 +03:00

158 lines
7.8 KiB
Markdown
Raw Blame History

# 136 — Planar Capture Component (`BPC_PlanarCapture`)
## Purpose
Core capture component managing `USceneCaptureComponent2D` lifecycle for mirrors, portals, monitors, and horror surfaces. All camera math, render target management, and per-frame capture decisions happen here in C++ for performance.
## Dependencies
- **Requires:** `SS_PlanarCaptureManager` (138) for quality tier assignment and RT pool, `UPlanarCaptureCameraUtils` for camera math
- **Required By:** `BP_PlanarCaptureActor` (137) — owned by parent actor
- **Engine/Plugin Requirements:** Renderer, RenderCore modules
## Class Info
| Property | Value |
|----------|-------|
| **Parent Class** | `ActorComponent` (C++ `UBPC_PlanarCapture`) |
| **Class Type** | Blueprint Component (C++ Full Implementation) |
| **Asset Path** | `Content/Framework/Capture/` |
| **C++ Header** | `Source/PG_Framework/Public/Capture/BPC_PlanarCapture.h` |
| **C++ Source** | `Source/PG_Framework/Private/Capture/BPC_PlanarCapture.cpp` |
| **C++ Status** | ✅ Full Implementation |
| **BP Asset** | None — use C++ component directly on actors |
## 1. Enums
*Defined in `PlanarCaptureCommon.h` — see Architecture doc for full listing.*
| Enum | Values | Description |
|------|--------|-------------|
| `EPlanarCaptureMode` | Mirror, Portal, Monitor, HorrorMirror, HorrorPortal, FakeWindow | Capture surface mode |
| `EPlanarCaptureQualityTier` | Off, Low, Medium, High, Hero | Quality tier levels |
| `EPlanarCaptureInitResult` | Success, NoRenderTargetPool, InvalidSurfaceMesh, BudgetExceeded, ManagerUnavailable | Init result codes |
## 2. Structs
*Defined in `PlanarCaptureCommon.h`*
### `FPlanarCaptureQualityProfile`
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `RenderTargetSize` | int32 | 512 | Square RT resolution (256/512/1024/2048) |
| `CaptureInterval` | float | 0.0667 | Min seconds between captures (~15fps default) |
| `bEnableShadows` | bool | true | Shadow rendering toggle |
| `bEnablePostProcess` | bool | false | Post-process toggle |
| `bEnableFog` | bool | false | Exponential height fog toggle |
| `bEnableBloom` | bool | false | Bloom toggle |
| `bEnableAO` | bool | false | Ambient occlusion toggle |
| `bEnableLumen` | bool | false | Lumen GI toggle (expensive) |
| `bEnableMotionBlur` | bool | false | Motion blur toggle |
| `bEnableClipPlane` | bool | true | Oblique near-plane toggle |
| `DelayedFrameCount` | int32 | 0 | Horror delayed frame ring buffer size |
## 3. Variables
### Configuration (EditAnywhere, BlueprintReadOnly)
| Variable | Type | Default | Category | Description |
|----------|------|---------|----------|-------------|
| `CaptureMode` | EPlanarCaptureMode | Mirror | `Capture\|Config` | Surface type |
| `QualityProfiles` | TArray〈FPlanarCaptureQualityProfile〉 | 4 entries | `Capture\|Config` | Quality profiles per tier [0=Low,1=Med,2=High,3=Hero] |
| `CaptureFOV` | float | 90.0 | `Capture\|Config` | Capture camera FOV |
| `MaxViewDistance` | float | 5000.0 | `Capture\|Config` | Max render distance |
| `ShowOnlyActors` | TArray〈FPlanarCaptureActorListEntry〉 | — | `Capture\|ActorLists` | Exclusive show actors |
| `HiddenActors` | TArray〈FPlanarCaptureActorListEntry〉 | — | `Capture\|ActorLists` | Hidden actors |
| `WrongReflectionActor` | TSoftObjectPtr〈AActor〉 | — | `Capture\|Horror` | Horror mode wrong reflection swap |
| `SurfaceMeshComponent` | TSoftObjectPtr〈UStaticMeshComponent〉 | — | `Capture\|Config` | Mesh for clip plane calculation |
| `LinkedTargetSurface` | TSoftObjectPtr〈ABP_PlanarCaptureActor〉 | — | `Capture\|Portal` | Portal destination surface |
| `FixedCameraActor` | TSoftObjectPtr〈AActor〉 | — | `Capture\|Monitor` | Monitor fixed camera |
### Runtime (BlueprintReadOnly)
| Variable | Type | Description |
|----------|------|-------------|
| `CurrentQualityTier` | EPlanarCaptureQualityTier | Assigned quality tier |
| `bIsCapturing` | bool | Is capture currently active |
| `CaptureRenderTarget` | UTextureRenderTarget2D* | Active render target |
## 4. Functions
### Public (BlueprintCallable)
#### `InitializeCapture()` → `EPlanarCaptureInitResult`
- **Description:** Allocates RT from pool, creates USceneCaptureComponent2D, configures show flags
- **Flow:** Request RT → Create SceneCapture → ApplyShowFlags → UpdateActorLists → Set bIsCapturing
- **Nodes Used:** `RequestRenderTarget`, `CreateSceneCaptureComponent2D`, `ApplyShowFlags`, `UpdateActorLists`
#### `ShutdownCapture()`
- **Description:** Stops capture, releases RT to pool, destroys SceneCapture2D
- **Flow:** Set bIsCapturing=false → DestroyComponent → ReleaseRenderTarget → Clear ring buffer
#### `ApplyQualityTier(Tier: EPlanarCaptureQualityTier)`
- **Description:** Apply a quality tier profile immediately. Called by SS_PlanarCaptureManager.
- **Flow:** If Off → ShutdownCapture. If transitioning from Off → InitializeCapture. Else → UpdateShowFlags + ApplyProfile.
#### `CaptureNow()`
- **Description:** Bypasses tick interval, captures immediately. Used for event-driven captures.
- **Blueprint Authority:** Any (local)
- **Flow:** Get viewer camera → ComputeCaptureCameraTransform → Set SceneCapture transform → CaptureScene → PushMPCParameters
#### `ActivateHorrorReflection()`
- **Description:** Saves original ShowOnly list, swaps to WrongReflectionActor
- **Flow:** Save ShowOnlyActors → Clear list → Add WrongReflectionActor → UpdateActorLists
#### `DeactivateHorrorReflection()`
- **Description:** Restores original ShowOnly list after horror event
- **Flow:** Clear list → Restore from SavedShowOnlyActors → UpdateActorLists
#### `SetScriptedPriority(Priority: float)`
- **Description:** Scripted priority override (0.0-1.0). Higher values force higher quality tier.
#### `PushMPCParameters(MPC: UMaterialParameterCollection*)`
- **Description:** Push all 10 MPC scalar parameters for surface material effects
### Compute (BlueprintPure)
#### `ComputeCaptureCameraTransform(ViewerCamera: FTransform)` → `FTransform`
- **Description:** Computes capture camera position based on mode (mirror reflection, portal relative, etc.)
#### `GetCurrentScore()` → `FPlanarCaptureScore`
- **Description:** Returns current composite quality score for this surface
## 5. Event Dispatchers
| Dispatcher | Parameters | Description |
|------------|-----------|-------------|
| `OnCaptureQualityChanged` | OldTier, NewTier | Quality tier changed |
| `OnCaptureInitialized` | Result: EPlanarCaptureInitResult | Init completed |
| `OnCaptureRendered` | — | Each frame rendered |
## 6. Communication Matrix
| Target System | Method | What |
|---------------|--------|------|
| `SS_PlanarCaptureManager` | Direct (cached reference) | RT requests, quality tier reception |
| `BP_PlanarCaptureActor` | Direct (owner) | Surface mesh, MPC reference |
| `UPlanarCaptureCameraUtils` | Static function calls | Mirror/portal/oblique math |
| `USceneCaptureComponent2D` | Direct (owns) | Full lifecycle control |
## 7. Manual Implementation Guide
*The C++ component is fully functional. Blueprint users interact through the public API:*
1. To force a capture (e.g., on a sequencer event):
```
Get BPC_PlanarCapture → Call CaptureNow()
```
2. To trigger a horror mirror wrong reflection:
```
Get BPC_PlanarCapture → Call ActivateHorrorReflection()
Wait (duration from curve) → Call DeactivateHorrorReflection()
```
3. To boost a specific mirror for a scare moment:
```
Get BPC_PlanarCapture → Call SetScriptedPriority(1.0)
Wait (scare duration) → Call SetScriptedPriority(0.0)
```
## 8. Build Checklist
- [ ] C++ component compiled and functional
- [ ] No BP child needed — attach directly to actor
- [ ] Configure QualityProfiles array in component defaults (4 entries)
- [ ] Set CaptureMode in component defaults
- [ ] Assign SurfaceMeshComponent reference
Reference in New Issue View Git Blame Copy Permalink