Debug Preview
Verify Vision capture in the Unity Editor with a live overlay showing the active frame source, capture statistics, and source state.
Visualising Vision Capture with Debug Preview
VisionDebugPreview renders the active frame source's output as an on-screen overlay inside the Unity Editor, giving you immediate visual confirmation that capture is working correctly. It also displays a live statistics panel showing frame rate, total frame count, and source state. Because this component is designed for development use, it automatically disables itself in player builds — it has zero runtime cost when you ship your project.
VisionDebugPreview is an Editor-only component. It disables itself automatically when running in a player build. Do not rely on it for in-game UI or production diagnostics.
Adding Debug Preview to Your Scene
Add the Component
Select any GameObject in the scene — the same one as your frame source, or a dedicated debug object. Click Add Component → Convai/Vision/Vision Debug Preview (Editor Only).
Assign a Frame Source (Optional)
In the Frame Source Component field, drag in the IVisionFrameSource component you want to preview. If you leave this blank and Fallback to Active Frame Source is enabled, the component automatically selects the first capturing source in the scene.
Enter Play Mode
Press Play. An overlay appears in the Game view showing the live texture and a statistics panel. Adjust position and size using the Inspector fields described below.
Inspector Reference
Frame Source
Frame Source Component
MonoBehaviour
(auto-resolved)
The frame source to preview. Leave blank to use fallback auto-discovery.
Fallback to Active Frame Source
bool
true
When the assigned source is idle or unassigned, automatically find and display the first actively capturing source in the scene.
Overlay Layout
Overlay Position
PreviewPosition
BottomRight
Corner of the Game view where the overlay is anchored.
Overlay Width
int (160–640)
320
Width of the preview overlay in pixels.
Offset X
int (0–200)
10
Horizontal distance in pixels between the overlay edge and the screen edge.
Offset Y
int (0–200)
10
Vertical distance in pixels between the overlay edge and the screen edge.
Aspect Ratio
Use Source Aspect Ratio
bool
true
Derives the overlay height from the frame source's actual capture dimensions.
Custom Aspect Ratio
float (1–3)
1.778 (16:9)
The aspect ratio used to calculate overlay height when Use Source Aspect Ratio is disabled.
Preview Settings
Show Preview
bool
true
Enables or disables the image overlay. Can be toggled at runtime.
Show Stats
bool
true
Enables or disables the statistics overlay. Can be toggled at runtime.
PreviewPosition Values
TopLeft
Upper-left corner of the Game view
TopRight
Upper-right corner
BottomLeft
Lower-left corner
BottomRight
Lower-right corner (default)
Statistics Overlay
When Show Stats is enabled, the overlay displays the following live values:
FPS
Frames per second currently being produced by the frame source
Frame count
Total frames captured since capture started
State
Current VisionSourceState of the frame source (e.g., Ready, Degraded)
Dimensions
Capture resolution in pixels
Runtime Scripting
VisionDebugPreview exposes a small scripting API for toggling the overlay and reading current statistics:
Known Limitations
VisionDebugPreview previews IVisionFrameSource.CurrentRenderTexture. It does not show the WebGL canvas capture path. On WebGL the overlay will appear blank or not initialise, because there is no frame source component in WebGL builds.
If no frame source is active and Fallback to Active Frame Source is false, the overlay shows a placeholder indicating that no capturing source was found. Enable fallback or assign the frame source explicitly to resolve this.
Conclusion
VisionDebugPreview gives you a live view of exactly what the character sees, along with capture statistics, at zero cost to your production build. Use it throughout development to verify frame source health, confirm capture is running at the expected frame rate, and catch issues before they reach players. For worked implementation examples, see Usage Examples. For production scripting patterns, see Advanced Topics.
Last updated
Was this helpful?