VLED Unreal Plugin User Guide

Overview

The VLED Unreal Plugin renders a live Unreal scene to a Voxel VX2 / VX2-XL volumetric display in real time. Drop a single actor into your level, position it over your subject, press Play, and the scene appears on the volumetric display for an audience to walk around and explore from every angle. Drive it from Blueprint or C++, just like any other actor.

What it does

Every frame, the plugin:

1. Renders the scene from six orthographic depth + colour cameras — one looking in at each face of a cube around your subject (±X, ±Y, ±Z).
2. Packs colour and depth and compacts it into voxels on the GPU using compute shaders.
3. Sends those voxels straight to the VX2 hardware via ledhost.dll on a background display thread, and opens a LedWin simulator window you can orbit and zoom.

The region that gets captured is shown in the editor as a green wireframe box (the camera faces) with an inscribed cylinder (the actual volume the VX2 shows) and a green text label on each face. Move and scale the actor to frame your subject, or use FollowTarget to track a pawn automatically.

All settings — capture resolution, voxel budget, gamma, sharpness, boost and face selection — are configured in the actor's Details panel and persist between sessions via Saved/VLEDConfig.json.

Requirements

• Windows and Unreal Engine 5.7 as a C++ project — the plugin contains native code.
• The Voxel runtime DLLs ledhost.dll, LedWin.dll and ledhost.ini, typically under C:/VLED/System/Runtime. These are installed as part of the VLED environment.

Quick start

1. Copy the plugin into your project's Plugins/VLEDUnrealPlugin/ folder and let the editor rebuild it (a C++ project is required).
2. Open your level. In Place Actors, search VoxelStudio and drag an UnrealVledPluginActor into the scene.
3. Move (W) the green volume over your subject and scale (R) it so the subject fills the box. (Tip: set FollowTarget to your pawn so it tracks automatically.)
4. Press Play — the feed starts and the simulator window opens.

Installing the plugin

The plugin contains C++, so the target project must be a C++ project (or be converted to one — adding any C++ class in the editor does this).

1. Copy the whole VLEDUnrealPlugin folder into your project's Plugins/ folder: <YourProject>/Plugins/VLEDUnrealPlugin/.
2. Open the project. Unreal detects the new plugin and offers to rebuild it — accept. (If it doesn't, right-click the .uproject → Generate Visual Studio project files, then build the <YourProject>Editor target.)
3. Confirm it's enabled in Edit → Plugins → Other → VLED Unreal Plugin.

Adding the actor to your level

1. Place Actors panel → search VoxelStudio → drag an UnrealVledPluginActor into the level.
2. The actor shows a green wireframe box + cylinder gizmo — this is the capture volume.
3. Frame your subject:
   • Move the actor (W) so the subject sits in the middle of the volume.
   • Scale the actor (R) to zoom: shrink to make the subject fill the display, grow to capture more of the scene.
   • Or set FollowTarget to your player/pawn so the volume tracks it during Play (use FollowOffset to raise it, e.g. 1 m above the feet; use FollowBoneName to track a specific animated bone on a skeletal mesh).

Only what's inside the volume is sent to the display.

Output

The plugin sends voxels straight to the VX2 hardware via ledhost.dll and opens the LedWin simulator window. On Play, a background thread opens the window, spins the motor, and streams voxels.

The runtime is located at the default path (C:/VLED/System/Runtime) automatically, so there's normally nothing to set. If your runtime lives elsewhere, point LedHostDllDir at the folder containing ledhost.dll, LedWin.dll and ledhost.ini.

The simulator window lets you orbit (left-drag) and zoom (mouse wheel) to inspect the volumetric output. All other settings are configured in the actor's Details panel.

Running

Press Play. Capture begins immediately (unless bCapturing is off).

Performance tips for a single-GPU machine:

• Keep MaxCaptureHz at 30 (the display's refresh).
• Enable bDisableViewportRendering to spend the GPU on the captures, not the editor viewport.
• Turn off faces you don't need — each face is a full scene render. The default enabled faces are PX, PY and Top; the other three are off.
• Leave bDisableHairRayTracing = true (prevents a GPU hang from MetaHuman hair rebuilding ray-tracing geometry 6× per frame).

Controls

Everything below works during Play (and during editor preview when bPreviewInEditor is on).

Positioning the capture volume

The volume is positioned by moving and scaling the actor itself — there are no runtime keyboard or SpaceMouse controls.

Method	How
Move the actor	Select the actor in the editor, press W, drag.
Scale the actor	Press R, drag to zoom: shrink = subject fills the display; grow = capture more of the scene.
FollowTarget	Set the actor's FollowTarget to your player / pawn so the volume tracks it every tick. Use FollowOffset to raise it and FollowBoneName to track a specific animated bone.

Simulator-window interactions

The LedWin simulator window (Direct Display) shows a software render of the volumetric output. Two mouse interactions work in the window:

Input	Action
Left-drag	Orbit — rotate the viewing angle around the volume.
Mouse wheel	Zoom — move the virtual camera closer or further from the volume.

There is no menu bar, no sliders panel and no keyboard navigation in the simulator window. All settings are configured in the actor's Details panel.

Editor gizmo

The capture volume is drawn (editor only — never in the VX2 output) as:

• a thin green wireframe box — the six camera faces (a cube for VX2, a squashed box for VX2-XL);
• an inscribed cylinder — the actual volume the VX2 displays;
• a green text label on each face naming its view (+X Right, +Y Front, −X Left, −Y Back, Top, Bottom).

The whole gizmo tracks the actor's position and scale, and reshapes when you switch format, so it always shows exactly what is being captured.

Settings reference

All settings live in the actor's Details panel. Changes during Play apply immediately, and settings are persisted automatically to Saved/VLEDConfig.json.

VoxelStudio

Property	Default	Description
Format	VX2	VX2 = 256 px faces, 2 m cube. VX2-XL = 512 px faces, 4×2 m box. Applies live (rebuilds GPU buffers).
bCapturing	true	Uncheck to pause the feed without stopping Play.
bPreviewInEditor	false	Run the capture pipeline in edit mode (transient — off on level load).
bDisableViewportRendering	false	Fully blank the main game viewport during Play to free the GPU. Restored on EndPlay.

VoxelStudio | Capture

Property	Default	Description
CaptureResolution	Medium	Per-face capture resolution: Low / Medium / High = VX2 128/256/512 px, VX2-XL 256/512/1024 px. Applies live.
CaptureTiltDegrees	30°	Pitch the 4 side cameras down so they catch the ground under the subject. 0 = flat.
bAntiMoire	false	Offset each capture camera's rotation slightly to break up moire/grid patterns in the voxel output.
AntiMoireDegrees	0.3°	Magnitude of the per-face anti-moire rotation offset. Only active when bAntiMoire is on.
MaxCaptureHz	30	Max capture rate (fps). 0 = full tick rate (wasteful).
bDisableHairRayTracing	true	Force r.HairStrands.Raytracing 0 on Play (avoids a GPU hang with MetaHuman hair).

VoxelStudio | Volume

Property	Default	Description
FollowTarget	none	Actor to track during Play; the volume follows its location + FollowOffset.
FollowOffset	(0,0,100)	World offset added on top of the follow target's location (default 1 m up).
FollowBoneName	None	Bone or socket on the target's skeletal mesh to track. Useful for animated characters whose actor root stays static.

VoxelStudio | Look

Property	Default	Description
Exposure	1.0	Manual exposure multiplier applied before the ACES tonemap. 1.0 = neutral. Reduce a lot for bright/outdoor scenes.
bAutoExposure	true	Meter the captured HDR each frame and adapt exposure automatically. When on, Exposure acts as an EV compensation.
AutoExposureSpeed	3.0	How quickly auto-exposure adapts (stops/sec).
AutoExposureCompensation	0.0	EV stops applied on top of auto-exposure (0 = neutral). Only active when bAutoExposure is on.
Gamma	1.0	Brightness curve applied by the VX2 (lower = brighter midtones).
Sharpness	128	VX2 dither threshold — higher = sharper point voxels, lower = smoother.
VoxelBudgetMillions	0.5	Max voxels (millions). The scene is thinned evenly when it exceeds this count.
bBoostX / bBoostY / bBoostZ	false	Duplicate each voxel along X/Y/Z by a short offset to brighten the image.
BoostDistanceMm	0.0	Boost duplicate offset distance in mm.

VoxelStudio | Faces

Each face is one orthographic camera. Disabled faces are skipped entirely (no capture/readback) — cheaper, but that side isn't seen. Each face is a full scene render, so enable more for more complete coverage at higher GPU cost.

Property	Default	Face
bEnableFace_PX	on	+X (right)
bEnableFace_PY	on	+Y (front)
bEnableFace_MX	off	−X (left)
bEnableFace_MY	off	−Y (back)
bEnableFace_Top	on	+Z (top)
bEnableFace_Bottom	off	−Z (bottom)

VoxelStudio | Output

Property	Default	Description
LedHostDllDir	C:/VLED/System/Runtime	Folder containing ledhost.dll, LedWin.dll and ledhost.ini. Defaults to the standard runtime path, so you don't normally need to change it.

VoxelStudio | Debug

Property	Description
bSimulatorBorder	Draw the VLED border in the LedWin simulator window.
bShowSimStats	Overlay VPS + per-volume render time (ms) on the LedWin window, coloured green/yellow/red vs the 30 VPS target.
bDebugShowFrame	Update DebugFrameRT each tick with the packed frame (apply to a plane material to inspect).
bDebugSaveSingleFrame	Save one packed frame as a BMP to Saved/VoxelStudioDebug/frame.bmp. Resets automatically.
bDebugTimingLog	Print a per-section timing breakdown to the viewport every 60 frames.

Packaging & deployment

Packaging works exactly like any standard Unreal project:

1. File > Package Project > Windows.
2. Choose a build configuration — Development for testing your packaged build, or Shipping for a final release build.
3. Unreal produces a platform output folder containing <Game>.exe plus supporting files.

The VLED plugin is a runtime module, so it's included in packaged builds automatically — there's no extra step to enable it for packaging.