The Video Surface Editor

Surfaces are designed to accommodate an extremely wide range of workflows and setups, from single screens, to video walls, to multi-projector blends on curved surfaces. As such, working with surfaces can be fairly straightforward or it can be very involved. The Video Surface Editor is where you set up your workspace to output video to the world.

To get to the Video Surface Editor, go to Workspace Settings and choose Video from the list on the left, then click the Edit button next to one of the video surfaces.

Getting started with surfaces

When you create a new workspace, QLab will automatically add a surface for each attached display, with that display assigned to the surface. That way, if you don’t need anything fancy you can start programming cues as quickly as possible. You can edit these surfaces to suit your needs, or you can delete them and create your own surfaces.

You can see the list of surfaces in your workspace by visiting Workspace Settings and choosing Video from the list on the left.

This screen shot was taken on a 2017 15” Retina MacBook Pro with a 25060x1440 monitor connected to the Thunderbolt port. When this workspace was created, QLab automatically created Surface 1 with the MacBook Pro’s internal display assigned to it, and Surface 2 with the external monitor assigned to it.

To create a new surface, click the popup button below the surface list in the Video page of workspace settings. There are three workflows for creating a new surface:

1. Select New Empty Surface to create a totally blank surface, to which you can add screens manually.
2. Select New With Display and choose a display to create a surface with that display assigned to the surface. The surface will be created at the same size as the display.
3. Select New Multi-Screen Surface to have QLab walk you through creating a surface with a number of regularly arranged screens, such as a multi-projector blended surface or an LCD video wall.

We’ll go into more detail about each of these options later on this page.

Once a surface is set up, you can make any number of copies of it by selecting the surface you want to copy and clicking the Duplicate button.

To edit a surface, click on the Edit button to the right of that surface’s name.

To delete a surface, click on the button all the way to the right of that surface’s name.

Surfaces that are broken will appear with a yellow exclamation point (), and cues routed to broken surfaces will also appear as broken. A surface is defined as broken if it has no valid displays attached. If at least one assigned display is available, the surface will not report as broken, although it will alert you to any disconnected displays in the surface list. Surfaces may also appear as broken if they use features not supported by any of your currently installed licenses.

The Video Surface Editor

Clicking the Edit button next to a surface brings up the Surface Editor in a separate window. We’re not going to lie to you: this is definitely the most complex-looking part of QLab, and there is a lot going on in this window. Give yourself plenty of time to learn about it, and remember that you can always write to support@figure53.com at any time if you have any questions, large or small, even if you haven’t bought a QLab license.

Many features visible in the Edit window require a Pro Video or Pro Bundle license, and will be disabled if an appropriate license is not installed. The features which are allowed without a pro license will function at all times.

The header area shows the surface’s name and pixel dimensions.

The leftmost column shows a list of all displays assigned to the surface, as well as a section for information and controls pertaining to the currently selected display.

The center column is occupied by the surface canvas, where you can arrange screens on the surface and adjust control points for each screen.

The right column contains controls for parameters of the surface itself, as well as the currently selected control point or split (when applicable).

Surface name. The name for a newly created surface defaults to something like “Surface 1” or “Surface 2”, and you can rename the surface here to whatever you like. Surface names must be unique within a workspace, so QLab will not allow you to rename a surface to have the same name as another surface.

Dimensions. Every surface in QLab starts its life as a rectangle measured in pixels. The size of the surface does not need to be anything specific, or follow any formula or ratio. If you are creating a surface that will only use one screen, and you want to use the whole of that screen, then the size of the surface should match the size of the screen. That is to say, if you are using a projector with a resolution of 1024x768, then your surface should have dimensions of 1024x768. There is no exact official limit to the size of a surface, but very large surfaces can require more VRAM than your computer has, which can lead to problems.

Displays

This area is where you add, remove, replace, and adjust the display(s) assigned to a surface. At the top is a list of all currently assigned screens, including the raster dimensions of each, and checkboxes to toggle the grid and guides for each. You can find information about grid and guides below.

To assign a screen to the surface, click on the button and select the screen you wish to add. If you have a Pro Video or Pro Bundle license installed, you can also choose partial screens or Syphon (explained just below).

To remove the selected screen, click the - button.

Syphon output

Although Syphon appears in the list of screens, it does not show up visually in the canvas view of the surface. Syphon output simply mirrors the full surface (within any constraints), with no warping applied. You can add Syphon to any number of surfaces within a QLab workspace; each will create its own Syphon server, so each surfaces can be made available to other Syphon-enabled applications.

Adding Syphon output to a surface has no impact on processor load or performance, because each surface already uses a private Syphon server internally to send frames to the renderers that output video to each display. Adding Syphon to a surface simply makes that server public, so there is no additional work happening within QLab. There is, of course, a CPU and GPU load associated with whatever application is on the receiving end.

You can learn more about Syphon here.

Partial screens

Display splitters such as the Matrox DualHead2Go and TripleHead2Go and the Datapath x4 show up to OS X as a single, very large display. Using partial screens in QLab allows you to split that large display back up and address each output of the splitter as an independent virtual display. Partial screens can be arranged as 2-wide, 3-wide, 4-wide, or 2⨉2.

Partial screens require a Pro Video or Pro Bundle license.

Partial screens are designed exclusively for working with hardware splitters, and are not useful for making a surface cover only part of a projector. Instead, to restrict a surface to one part of a projector, use constraints, or simply reduce the surface dimensions and adjust the screen’s origin.

Replace Screen

The Replace screen drop-down allows you to select a screen from the list, and then remap that screen to a different display. The drop-down lists only displays which are currently connected to your Mac. This is helpful if your hardware has changed, for example if you’ve prepared a show using an external monitor, then moved to the theater where you’re using a projector. It can also help you if OS X mistakenly identified a screen as new, when in fact it’s the same display you’ve been using. When you replace a screen, QLab updates the screen’s raster dimensions to match the new display, and any adjustments you’ve made such as control points are preserved as closely as possible.

Screen Controls

The lower section of this column contains controls for the currently selected screen:

Origin controls determine (in X and Y pixels) the position of the screen’s lower left corner relative to the lower left corner of the surface.

Orientation controls are composed of the Rear checkbox, which flips the screen’s rendering horizontally for rear projection, and a Rotation pop-up, which rotates the image in 90° increments.

Edge blending can be disabled on a single projector (for example, if the projector has its own built-in blend controls) by unchecking this checkbox. This control is checked by default, but has no effect if the surface doesn’t contain at least two partially overlapping screens.

If the selected screen corresponds to a Blackmagic DeckLink-compatible device, a pop-up button will appear for selecting the resolution and frame rate of the device output.

Edge blending

QLab automatically detects when edge blending should happen and feathers the edges of each screen as appropriate, according to the following rules:

• If two screens overlap by more than 90%, they will be treated as double-stacked, and QLab will send the same image to both screens. For example, if you have two projectors that you want to combine to make a brighter image, overlapping them completely will tell QLab to mirror the output to the two projectors.
• If two screens overlap by more than 0% but less than 90%, QLab will automatically feather the overlapping edges, to create a seamless blend between projectors, unless you have disabled blending for the surface or its screens.
• If two screens do not overlap at all, the displays will render as separate parts of the surface with no blending.

The Reset control points button returns all the perspective/warping control points of the current screen to their default locations.

The Editor Canvas

The canvas shows a visual overview of the surface layout. With a Pro Video or Pro Bundle license installed, you can drag screens to arrange them on the surface, drag splits to adjust them, and drag control points to adjust perspective correction and warping.

The surface is displayed as a white rectangle with a black focus grid. The name and dimensions of the surface are displayed in the center of the surface. Screens assigned to the surface appear as translucent colored rectangles, also labeled with their name and size. If your surface is 1024x768 and you assign a screen that is 1024x768, then the screen will cover the entire surface. If the surface is larger, you’ll see that part of the surface is covered by the screen, and part is not.

The canvas is bordered on the top and left by rulers that show surface measurements in pixels. These measurements are centered relative to the middle of the full surface, before any constraints.

The drop-down menu in the lower right corner of the canvas allows you to scale the view in the Surface Editor. It has no effect on QLab’s output.

Surface Controls

The controls in this column represent parameters of the surface itself.

Warp type

Warping controls require a Pro Video or Pro Bundle license.

Each screen assigned to a surface comes with a set of control points that you can use to warp the final rendering in various ways. This allows you to project a flat image onto an object that is oddly shaped or at an angle to the projector, and have it appear perfectly aligned to the audience.

Each screen starts off with control points in each corner. You can add splits to a surface in order to add more control points.

Control points are associated with individual screens, so warping adjustments made to one projector will not affect the image displayed by another projector on the same surface.

Note that it is best to arrange all the displays on a surface, and split the surface as desired, before adjusting control points. We haven’t discussed splits yet, but that’s coming up real soon.

QLab offers three types of warping. Each surface can use any of the three types:

• Perspective (the default mode) is useful for simple vertical and horizontal keystone correction, also called corner pinning) when you’re projecting onto a flat surface that the projector is not perfectly aligned with. Any adjustments made are perspective-correct, meaning that once the correction is complete, an image in one part of the surface will appear exactly the same size if moved to a different part of the surface.
• Linear is more useful for warping onto a complex shape; this is often called mesh warping. Linear warping guarantees a continuous image across a split, with the tradeoff that it is not perspective-correct, and may distort images if used with extreme corrections.
• Bézier is a more complex mode, used to project onto curved surfaces. This mode gives you more control points, for full control of a 2D cubic Bézier surface. Like Linear mode, it is continuous across splits and useful for mesh warping.
• Hint: Bézier warps take longer to set up because of the additional control points; however, if you need to make a quick perspective tweak to a Bézier warp, you can do so by holding down the Command key while dragging one of the corner points. While Command is held down, QLab will interpolate the other points to approximate a perspective-correct corner pinning adjustment. This is not entirely precise, but it can be useful for minor tweaks.

Perspective correction is the most common use of QLab’s warp controls. In the simplest case, a single projector directed at a flat screen may need corner pinning in order to compensate for skewing or keystoning caused by the angle of incidence of its beam.

To make corrections such as these, first check the Grid checkbox for the display being corrected, to display an adjustment grid on the projector. Then, in the canvas of the Surface Editor, drag the yellow control points at the corners until the grid displayed by the projector appears aligned. Fine-tune these adjustments, if desired, by holding down the Shift key while dragging control points, or by adjusting the selected control point numerically using the Selected control point fields in the right column of the Surface Editor. When finished, uncheck the Grid checkbox to dismiss the grid.

In many cases, multiple projectors are edge-blended onto a single screen. Since each beam may hit the screen at a different angle, each projector has its own set of control points. It may be helpful to work with one projector at a time, adjusting control points with only a single grid shown, then to fine-tune the control points with all grids up and ensure that they overlap continuously.

Whenever possible, QLab attempts to adjust control points automatically to match other changes you make to a surface, such as moving screens or changing the layout of splits. However, once control point adjustments have been made, it is generally not possible to interpolate correct new locations for the control points when the surface setup changes. Rather than wildly guessing in these cases (since manual adjustment will be necessary anyway,) QLab leaves the control points in place for you to adjust. This can cause the image to appear distorted until you fix the control points, because they no longer match closely with the area they represent.

You may notice that the first adjustment you make to a screen’s control point causes that screen’s outline in the canvas to appear thicker. This indicates that an adjustment has been made, and the control points are fixed in place relative to the screen until you adjust them yourself. If you click on the Reset control points button, the thinner outline will return, and the control points will begin automatically adjusting to match the changes you make.

Usually, saving control point adjustments for the end of the process is the easiest way to ensure that moving screens and splits doesn’t distort the image, and that the control points all start from a reasonable starting place. If that order of operations is not possible, you can still adjust control points manually, or use the Reset control points button to start fresh.

Constraints

Constraints are a means of taking an existing surface and bringing its sides in to reduce its effective dimensions, while preserving all the warps and splits previously defined on the surface. The result, for the purposes of cue geometry, is simply a smaller surface.

To constrain a surface, click on the Constraints… button, and use the number fields in the popover to bring in each edge.

Constraints are most useful in conjunction with duplicating surfaces. For example, if you have a paneled wall defined as one surface, and want to define the individual panels as separate surfaces, you can first set up the full wall, along with any control point adjustments, then duplicate that surface and pull the duplicate’s constraints in to isolate a single panel. This saves time compared to redoing all the corner pin adjustments to match the full wall’s geometry perfectly.

Splits

Adding splits divides a surface up into separate regions, called “patches”, each of which has its own set of control points. This allows you to map your surface onto complex shapes, like the corner of a set piece or the façade of a building.

To add a split, click on the Add split… button. In the popover that appears, choose whether to split the surface horizontally (resulting in a left half and a right half) or vertically (into a top half and a bottom half), and provide the location for the split. You can set the location by clicking in the number field and dragging up and down. A thin dotted line will appear in the surface canvas as a preview, and will appear thicker once you click on Add split to commit it.

To move an existing split, click and drag it in the surface canvas. You can also adjust its positioning numerically by clicking to select it in the canvas, then using the Selected patch field.

To delete a split, click to select it in the canvas, then click the X button next to the Selected split field.

Once a surface is split into patches, each patch is labeled with an identifier such as A1, A2, B1, etc. These labels show up in two places: The surface itself is displayed with large gray labels, and each display on the surface is shown with smaller, colored labels for patch identifiers. This allows you to determine which part of the surface corresponds to which set of control points, even if the control points are dragged to a different part of the editor than the surface patch they correspond to.

It is important to note that each set of control points on a screen corresponds only to the part of the surface patch they intersect, and not necessarily to the corners of the whole patch. For example, if a 1920x1080 surface is split evenly, at x = 0, into patches A1 and B1, and the first projector ends just 10 pixels to the right of that split, then the control points labeled B1 for that projector will control only that 10-pixel-wide strip, and not the whole 960-pixel width of patch B1.

If you move a screen until it no longer intersects with a patch at all, the number of control points associated with that screen will change. This can have unexpected results if you have control point adjustments in place, as it may change which patch a set of control points corresponds to. Again, saving control point adjustments for the end of the process will avoid this confusion.

Blend gamma

This adjusts the curve of the edge blending calculated by the surface. Adjust this if you see a dark or bright band running down the “seam” between projectors.

Surface Layer

The layer control for surfaces behaves just like the layer control for Video cues, but it’s a separate control. So if surface “Hamlet” is set to layer 1, and surface “Ophelia” is set to layer 2, then all cues assigned to Ophelia will render on top of all the cues assigned to Hamlet.

Surface Mask

Surface masks are a way to completely or partially block certain pixels of a surface from displaying. They may be a familiar concept from graphics editing software, and they work similarly in QLab. Masks have several uses, including:

• Altering the shape of otherwise rectangular surfaces.
• Feathering the edges of a surface for a vignetting effect.
• Defining a region where another surface shows through from underneath.

To add a mask to a surface, double-click on the Mask well and select a file, or drag a file from Finder onto the well.

A mask should be a greyscale image that matches the dimensions of the surface, but QLab will convert it to greyscale and re-size it to fix the surface if necessary.

Black pixels in the mask are regarded as opaque, white pixels are regarded as transparent, and grey pixels are partially transparent; the darker the grey, the less transparent they are.

Any standard image format can be used as a surface mask. There is no performance difference between formats when rendering because QLab re-renders the image when importing it for use as a mask. However, if the size of the mask image is different from the size of the surface, QLab must scale it “live” and that can negatively affect performance, so try to match your surface dimensions whenever possible.

QLab does not have an integrated mask editor. Instead, it watches the mask image file to look for changes; when it sees that the file has changed, it automatically reloads it. Thus, you can use any graphics editing program to make adjustments to a mask, and see changes applied live as you go.

Guides

The Guides checkbox toggles a set of lines and targets for projector alignment. With the basic layout of screens on a surface in place, you can use the guides to “rough in” the projectors to cover the desired physical area on stage.

Red guides show you the edges and center of each projector, and a green dotted line shows where the overlap with each adjacent projector should end. Guides show the bounds of the full projector raster, and are not affected by control points.

Grid

Use the Grid checkbox to send a black-and-white grid image to each projector while you adjust control points. The grid’s dimensions match those of the surface, and only the portion corresponding to the area covered by each projector is output. In other words, it is essentially equivalent to running a video cue with a still image of a grid in full-screen mode, except that it can be sent to individual screens in isolation. When all corner points are in place and grids for all screens are enabled, you should see a single, perspective-correct, continuous grid for the whole surface.

By default, the grid is rendered black-on-white; use the Invert checkbox to switch it to white-on-black.

The Save grid image… button creates an image file that can serve as a useful reference when constructing or fine-tuning masks in a graphics program.

Keep rendering between cues

Whenever a Video, Camera, or Text cue is running, QLab renders a black background on the whole surface that the active cue is assigned to. If no cues are playing, QLab does not show a black background, which allows the desktop to show through. If this checkbox is checked, however, QLab will keep rendering the black background until QLab quits or the workspace receives the command to panic. This can ensure a smoother transition between Video cues, particularly on Macs whose GPU performance is possibly not quite as terrific as one might wish.

Selected point or split controls

Below the Grid controls are fields for numerically adjusting the selected control point or split. When none is selected, these controls are hidden.

Surface ID

When a surface is created, QLab gives it a unique surface ID number. This number can be useful when using OSC or AppleScript to interact with surfaces. The surface ID is displayed in the lower right corner of the Surface Editor for easy reference and copying.