SurfaceCast

SurfaceCast reference

Every screen and every control, as a lookup. If you want to be taught how to run a show, read the user guide instead — this is the thing to reach for when you are in front of the application and want to know what one particular box does.

Ranges and limits below are the ones the application enforces.

Contents

The control panel

The main window. Five regions:

Region What it is
Layers (left dock) The object stack for the scene being edited, and the buttons that add objects. Closable; View ▸ Panels ▸ Layers brings it back.
Preview (center) The scene being edited, with editing overlays. Not the output.
Properties (right dock) Everything about the selected object. Closable, same as Layers.
Scene strip (bottom) One slot per scene, with the cue settings under each.
Status bar Show timer, remote, lights, projector, and a message line.

Status bar

Read right to left, these are permanent indicators rather than messages:

Indicator Meaning
Show timer Counts down the active scene when the timer is running; blank when it is not.
Remote The address the remote is serving on, and the last device that used it. Blank when off.
Lights Lights: n — how many LEDs or fixtures are being driven. Lights: ! means switched on but not sending; the tooltip says why. Blank when off.
Projector Which screen the output window is on, or Projector: closed.

File

Item Shortcut What it does
New scene Ctrl+N Empties the slot being edited.
Open scene… Ctrl+O Loads one scene file into the slot being edited.
Save scene Ctrl+S Saves the edited scene back where it came from.
Save scene as… Ctrl+Shift+S Saves it somewhere new, and remembers that as its file.
Open show… Loads a whole show — every slot at once.
Save show… Saves every slot into one file.
Recent shows The last ten shows, most recent first.
Open media folder Opens the media folder in the file manager.
Settings… Ctrl+, Settings.
Exit Ctrl+Q Offers to save anything unsaved first.

Edit

Item Shortcut What it does
Undo Ctrl+Z Fifty steps, per scene. Covers edits made from the phone too.
Redo Ctrl+Y Ctrl+Shift+Z also works.

Object

Item Shortcut What it does
Add video Ctrl+1
Add image Ctrl+2
Add color / gradient Ctrl+3
Add mask Ctrl+4 Blanks spill off something that should stay dark.
Add image with mesh warp Ctrl+5 For surfaces that are not flat.
Add video with mesh warp Ctrl+6 Costs more than a flat layer; see the performance notes.
Add from media A submenu of what is in the media folder, rebuilt each time it opens.
Duplicate Ctrl+D
Delete Del
Aiming grid for this object A Replaces the object's content with an alignment grid on the output. Never saved.
Clear every aiming grid Shift+A
Raise / Lower Ctrl+Up / Ctrl+Down Move the object through the stack.
Convert to mesh warp Turns a flat image or video into the mesh-warping kind, keeping its placement.
Convert to plain layer The reverse. The mesh is discarded.

A scene holds at most 32 objects; the 33rd is refused with a message.

Scene

Item Shortcut What it does
Edit scene 1–9 Alt+1…Alt+9 Opens a scene for editing without putting it on air.
Take queued scene Space
Load media for edited scene Ctrl+L Decodes this scene's media now, so taking it is instant.
Re-check all media Ctrl+R Re-reads every scene's files — use after a drive comes back.
Show timer (auto-advance) Ctrl+T Toggle.
Scene duration… Ctrl+Shift+T How long the timer holds this scene. Zero means hold.
Rename scene… F2
Add a scene slot Ctrl+Shift+N Up to 20.
Remove the last slot Down to 1.
Move this scene left / right Ctrl+Shift+Left / Right Reorders the strip.
Clear this slot Empties it.

View

Item Shortcut What it does
Panels ▸ Layers / Properties Show or hide each dock.
Panels ▸ Reset panel layout Shift+F5 Puts the docks back where they started.
Layout mode (handles) L Drag handles and a grid on the preview, for placing objects.
Keystone / corner pin W Drag the four corners. While it is on, Tab steps between corners.
Alignment grid G Preview only — never drawn on the output.
Snap to grid Shift+G
Safe-area guides
Cue settings on the scene strip Hides the per-slot cue controls once a show is built.

Output

Item Shortcut What it does
Projector window F5 Opens or closes the fullscreen output.
Blackout B Blanks the output without changing the live scene. Takes the lights with it.
Projector screen Which screen the output uses.
Identify screens Flashes the screen number on every display.
Remote control (phone) Toggle. Asks first — it has no password.
Lights follow the output Toggle. Refuses, with a reason, if there are no zones or nowhere to send.
Light zones… Light zones.

Help

Item Shortcut What it does
Help and keyboard shortcuts F1 The help window. Modeless.
User guide… / Hardware test plan… / Scene file format… / Mesh video performance… / License… / Third-party notices… Open each bundled document in the reader.
Save diagnostics report… One file with versions, screens, slot state, settings and the log tail. The file to attach to a bug report.
Open log folder logs\surfacecast.log beside the settings.
About SurfaceCast Version, licence, and the address to send a bug report to.

Layers panel

The object stack for the scene being edited. Index 0 is the top — the first row is drawn over everything below it, which is how the list reads on screen.

Add buttons: Video, Image, Color, Mask, Mesh image, Mesh video.

Then Raise and Lower (arrow buttons), Duplicate, Delete, Aim.

Each row shows the object's name and a one-line summary of what it is. The footer counts objects against the 32 limit.

Properties panel

Everything about the selected object. The first group is the same for every type; the rest depend on what it is.

Object (every type)

Control Range What it does
Type What this object is. Not editable.
Name What it is called in the layer list.
Visible Untick to hide it without deleting it.
Locked Stops it being dragged in the preview.
Opacity 0–1
Vignette 0–1 Fades the object's edges to transparent, so it settles into the surface instead of ending on it. 0 is off.
Shape Edge feather · Radial Edge feather keeps the center at full brightness and fades only the borders. Radial fades outwards from the center.
Show an alignment grid instead of content Aiming mode. Replaces this object's content with a grid on the output. Never saved — a show reopening with grids on stage would be a nasty surprise.

Transform (every type)

Control Range What it does
Rect — X, Y, W, H % of canvas Placement, as a share of the canvas rather than in pixels, so a show survives a change of projector.
Rotation −180° to +180° About the rectangle's center, in pixel space, so 45° looks like 45° on a non-square canvas.
Pixels The resulting size and position in output pixels, and the canvas size. Not editable.
Keystone Whether a corner pin is applied. Not editable.
Fill output Sets the rectangle to the whole canvas.
Center Centers it without changing its size.
Reset keystone Clears the corner pin, leaving the rectangle alone.

Video

Control Range What it does
File The clip. Browse… picks one.
Status Whether the file is readable, and its duration.
Scaling Fit inside (letterbox) · Fill and crop · Stretch to fit How the frame fits the object's rectangle.
Loop continuously
Play when scene goes live Off means it sits on its first frame until you start it.
Restart from the in point on each take Off leaves it wherever it was.
Speed 0.1–4.0 Playback rate.
Trim seconds In and out points.
Transport Play / Pause and Restart, for checking a clip while editing.
Position Scrub bar, with the time beneath it.
Mute this layer
Volume 0–1 Multiplied by the master volume in Settings.
Output System default, or a named device Which audio device this layer plays through.

Image

Control Range What it does
File Browse… picks one.
Status Whether the file is readable.
Scaling Fit inside (letterbox) · Fill and crop · Stretch to fit
Smooth Smooth scaling. Turn it off for pixel art.
Flip H · Flip V Mirror horizontally or vertically.

Color / Gradient

Control Range What it does
Type Solid color · Linear gradient · Radial gradient · Conical gradient
Angle −360° to +360° Linear and conical only.
Center % Radial and conical only.
Radius 0.01–4.0 Radial only.
Stops The color stops, as position and color. Add stop, Remove, Reverse (flips the order, so a fade one way becomes a fade the other).

Mask

A mask paints over whatever is beneath it, so it blanks spill off something that should stay dark.

Control Range What it does
Shape Rectangle · Ellipse · Polygon
Invert (mask everything outside the shape) Turns the mask inside out: the shape becomes the hole.
Feather 0–1 Softens the mask edge.
Corner radius 0–1 Rectangle only.
Color What the mask paints. Black for blanking; anything else is a flag.
Points 3–16 sides Build regular polygon replaces the points with an even-sided shape. Polygon only.

Mesh (mesh image and mesh video)

Control Range What it does
Cells 1–16 each way How finely the surface is divided. More cells fit a curve better and cost more to draw.
Flatten the grid Throws the warp away and leaves a flat rectangle.

Pull a mesh point with W and drag. Tab steps between points; Alt+arrows nudge the lit one, and Ctrl makes the nudge ten times coarser, not finer.

The scene strip

One slot per scene, 1–9 on the keyboard for the first nine.

Left click takes a scene live straight away. Ctrl+left click loads its media and opens it for editing without changing the output. Right click, or press and hold on a touch screen, opens the scene menu; a middle click does the same on a mouse that has the button.

The number keys work the other way round: 1-9 queue a scene, and a second press — or Space — takes it.

Each slot shows its number, name, status, object count and whether it holds media. The status reads LIVE, Ready, Loaded or empty.

Under each slot, unless View ▸ Cue settings on the scene strip is off:

Control What it does
hold / duration How long the show timer holds this scene. hold means stop here.
Cut / Fade How the scene arrives when taken.
seconds How long the fade takes. Grayed out on a cut, but the value is kept.

Arrows appear at the ends when there are more scenes than fit; the strip scrolls sideways.

The scene menu (right click)

Take live · Queue · Load media · Edit · New scene here · Open scene here… · Save this scene… · Rename… · Copy to scene ▸ · Duration… · Background… · Lights… · Notes… · Transition ▸ (Cut, Fade, Fade time…) · Move this scene left / right · Unload media · Clear slot.

The heading names which scene the menu is about, and Lights… shows that scene's cue, so the strip reads like a cue sheet.

The preview

The scene being edited, which is not always the scene on air — the header says EDIT — NOT LIVE when they differ.

  • Drag an object to move it. Handles appear in layout mode (L).
  • Keystone mode (W) drags the four corners instead.
  • Arrows nudge by one output pixel, Shift+arrows by ten.
  • Page Up / Page Down rotate.
  • The alignment grid (G) and safe-area guides are drawn here only, never on the output.

The projector window

Borderless, fullscreen, no cursor. It is a second view onto the same scene the preview shows, minus the editing overlays.

  • F5 opens and closes it; Esc closes it from the window itself.
  • Keys pressed here are forwarded to the control panel, so shortcuts work from either window.
  • Anything past the canvas edge is masked black, so an object dragged off the side cannot throw light onto whatever is beside the surface.
  • With nothing live it says so rather than going quietly black — that is how you tell an unassigned output from a dead cable.

Settings

File ▸ Settings, Ctrl+,. Five tabs. The window is capped to the screen's height and each page scrolls, so the OK and Cancel buttons are always reachable.

Output

Control Range What it does
Screen Which display the projector window uses. Identify flashes the number on every screen.
Open the projector window at startup Only takes effect once a screen has been chosen.
Match the canvas to the screen resolution On by default. The canvas follows the projector's native resolution, which keeps the output a 1:1 map.
Canvas 320–16384 each way The canvas size, when the box above is unticked.

Console

Control Range What it does
Show the alignment grid Preview only.
Grid divisions 2–64
Snap objects to the grid
Show safe-area guides
Master volume 0–100 % Multiplies every video layer's own volume.
Confirm before taking a scene live Asks before a click puts a scene on air. Worth it on a machine where the strip is easy to catch.

Files

Two groups: Autosave and recovery, and Media folder.

Control Range What it does
Keep a recovery copy while work is unsaved On by default. The only thing between a crash and hours of rig work.
Every 15–900 s How often the recovery copy is written.
File Where that copy lives. Not editable.
Folder The media folder. Browse… picks one, Open shows it in the file manager. Empty means the default.

Remote

Control Range What it does
Control the show from a phone or tablet Off by default, and it has no password.
Network Which adapter to listen on. Includes a this computer only entry.
Port 1024–65535 50505 unless changed, and it does not move on its own. Use default puts it back.
Address The address to type into the phone. Not editable.
Allow editing scenes from the remote On. Untick once a rig is aligned — there is no undo for a mis-drag from a phone.
Allow uploading media from the remote Off by default, and separate from editing: everything else the remote does stays inside the show, while this writes files onto this machine.

Lights

One group, Practical lights (WLED). The rig itself is not here — zones are aimed against the picture, so they live under Output ▸ Light zones. This page is what stays the same whatever the rig looks like.

Control Range What it does
Send the projected colors to a light controller Off by default.
Controller The WLED controller's address, as shown on its own web page.
Port 1–65535 21324, WLED's realtime port. Not the port its web page is on. Use default puts it back.
Refresh 10–60 per second How often the lights are updated. 30 is smooth and costs about a hundredth of a core.
Saturation 0.00–2.00 How far the sampled colors are pushed from gray before they are sent. An average over a region is always paler than the region looks, so a rig following a picture usually wants more than 1 — about 1.5 turns a soft green into a clear one. Brightness does not change, and white, black and gray pass through untouched, so a highlight stays white. At 0 the lamps follow brightness with no color. Applies to every lamp, WLED and DMX alike.

Light zones

Output ▸ Light zones. The rig: where the lamps are and where their colors go. Kept with this computer, not in the show file.

The picture on the left is the live output with the zones drawn on it, each filled with the color it is currently sending. Drag a zone to move it, drag the square in its bottom-right corner to resize.

Controller

Control Range What it does
Send to the lights Same switch as Output ▸ Lights follow the output.
Address The WLED controller. One controller, named outright — SurfaceCast does not broadcast.
Port 1–65535 21324 by default.
Refresh 10–60 per second
DMX Off · Art-Net · sACN / E1.31 · USB adapter How DMX zones leave the machine.
Node Art-Net: the node's address, required. sACN: empty multicasts, which reaches only nodes patched to the universe.
Adapter USB only. The serial port, named with what it reports itself as. Rescan looks again. A port that is set up but missing shows as (not connected).
Carries universe 1–63999 USB only. A widget has one DMX line, so it sends this universe and nothing else.
Fixtures… Fixtures.

Build a layout

Both replace every zone.

Control Range What it does
Grid 1–64 × 1–64 A rectangle of zones, numbered left to right then top to bottom. A strip along one edge is a grid one row deep.
Edges 1–64 a side A ring round the border, clockwise from the top left — how ambient strip is usually hung.

Zones

Add, Duplicate, Remove, Clear, then for the selected zone:

Control Range What it does
Name
Left · Top · Width · Height % of canvas The rectangle this zone averages.
Goes to WLED strip · DMX fixture Which rig this zone drives.
First LED 1–4096 WLED only. Counts from 1, the way WLED's own segment editor does.
Universe 1–63999 DMX only.
Channel 1–512 DMX only. The fixture's first channel, counting from 1.
Fixture DMX only. Which profile lays the color out.
How many 1–4096 How many LEDs, or how many fixtures in a row, take this color.
Wiring Rows, left to right / Rows, folded back each row / Columns, top to bottom / Columns, folded back each column / Reverse what it is now With Renumber, hands out pixel indices in the order the strip was actually run. For a rig of one-pixel zones from Grid or Edges, which put the zones in the right places and number them one particular way. Zones keep their places and their list order; only First LED changes.
Run direction One color across the run / Left to right / Right to left / Top to bottom / Bottom to top Which way this zone's pixels travel across its rectangle. One color averages the whole rectangle and gives every pixel the same color — what a wash wants, and what every rig did before this existed. The four directions divide the rectangle into as many slices as there are pixels, so each reads its own part of the picture; the name says where the first pixel sits.
Gain 0.0–4.0 Brightens or dims this zone alone. A practical next to a projected wash usually wants less than the picture. Brightness only: above the point where the brightest channel reaches full, the color stops changing rather than fading towards white.

A rig drives at most 4096 LEDs.

Scene light cue

The scene's right-click menu, Lights…. What this scene tells the lamps to do. Saved in the scene file, so it travels with the show.

The picture is that scene's own output, not whatever is on air. Zones can be clicked to select one, but not dragged — moving a zone is a change to the venue's rig, and doing it from inside a scene would be a trap.

Three groups: In this scene the lights (the three modes), Level, and Held colors.

Control Range What it does
Follow the picture Colors come off the projection. The default, and what a scene with no cue reads as.
Hold a color The lamps sit still whatever the picture does.
Stay dark Dark for this scene only, without blacking the projector out.
Intensity 0–200 % This scene's level, on top of each zone's gain. Multiplies with it, and like gain it changes brightness without changing the color.
One color for every zone One color is also what survives moving to a venue whose rig has a different number of zones.
Pick a color… Sets the held color — for the selected zone, or for all of them.
Use what is on screen now Freezes what the zones are reading off this scene. Usually the quickest way to author a hold.

A cue arrives over the scene's own transition time, so a three second fade moves the lamps over three seconds.

Fixtures

Output ▸ Light zones ▸ Fixtures…. How a kind of lamp lays its channels out.

Two are built in and cannot be edited:

Profile Channels
RGB (3 channels) red, green, blue
Dimmer + RGB (4 channels) dimmer (held at full), red, green, blue

The four-channel one is the one that catches people out: send a four-channel par three channels and it stays dark however right the color is.

Fixtures

Add (starts from dimmer + RGB), Copy, Remove, and a name field. Renaming takes any zone using it along too. Removing one leaves zones that named it falling back to plain RGB — lit wrongly rather than silently stopped.

Channels

Control Range What it does
How many channels 1–64 The fixture's DMX footprint.
Channel n role Red · Green · Blue · Dimmer (held) · Hold a value Red, green and blue follow the picture. Everything else is held where you put it.
Channel n value 0–255 For held roles only; grayed out on a driven channel.

There is no white or amber role. Mixing those well is a per-fixture judgement, so they are held channels set to whatever suits.

Find a channel

How to describe a lamp whose manual you do not have. It sends live.

Control Range What it does
Patched at — Universe / First channel 1–63999 / 1–512 Where the fixture is.
Sweep channel 1–64 Sends that one channel with every other channel at zero, so whatever moves is that channel.
(slider) 0–255 The value being swept.
Send now Starts sending. Unticking sends a blackout, so the lamp does not stay stuck.
Test color… With Sweep off, the whole fixture is sent this color — how you check a profile once it is built.

Help and document windows

F1 opens the help window: three tabs — Getting started, Keyboard, Mouse. It is modeless, so it can stay open while you work. The menu shortcuts it lists are read from the menus themselves, so they cannot fall out of step with the application.

The Help menu also opens each bundled document in a reader window with a chooser at the top, so an installed copy carries its own documentation and needs nothing registered for .md files. Open the folder shows the same files on disk.

The phone remote

A web page on the local network. Off by default and it has no password — see Settings ▸ Remote.

Control What it does
Scene buttons Tap to queue, tap again to take — the same rule as the number keys.
TAKE QUEUED Same as Space on the console.
BLACKOUT
SHOW TIMER Start and stop.
Edit mode A switch. With it on, tapping a scene opens its objects instead of queueing it. Opening a scene to edit never puts it on air.
Media Opens the media folder page.

In edit mode: undo and redo, the scene's Active for time and Transition, an arrow pad with move / size / rotate / keystone modes, corner buttons for the keystone, and the common object properties.

The Media page lists what is in the media folder. Add photos or video appears only when uploading is allowed in settings; it is off by default.

Phone edits go on the same undo stack as the console's, so either end can take back what the other did.