UE5-Modular-Game-Framework/docs/blueprints/17-capture/136_BPC_PlanarCapture.md

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