QLab uses an abstraction called Surfaces to output video. A surface in QLab is a virtual video output which has one or more actual video output devices assigned to it. By creating QLab surfaces which represent the physical surfaces onto which you’re projecting, QLab allows you to focus on the contents of your design rather than the mechanical details of your projection system.

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, there’s a lot of potential for complexity; the concept of surfaces allows that complexity to be isolated from the process of cue programming.

download video ↓

License requirements

The free version of QLab allows you to work with the simple case of outputting video to a single screen that you choose as a default surface for the workspace. The various advanced features introduced by QLab’s surface setup require different licenses, as follows:

Feature	Free (no license installed)	Basic Video	Pro Video
Single-screen surfaces	One*	Unlimited	Unlimited
Multi-screen surfaces		✔
Screen layers	✔	✔	✔
Alignment guides	✔	✔	✔
Adjustment grids	✔	✔	✔
Edge blending		✔
Splits and warping		✔
Masks and constraints		✔
Screen rotation		✔
Partial screens		✔
Syphon output		✔

* Multiple single-screen surfaces can be created without a license, but only the default surface can be used to play cues.

Basic structure

As a rule, each surface in a QLab workspace corresponds conceptually to a physical surface on the stage. For example, you may be projecting onto two walls and a door, all at different angles and all covered by one projector, in which case you will have three surfaces defined in your workspace (“Wall SL”, “Wall SR”, “Door”). Or you may have four projectors edge blended on a scrim, in which case you will have just one surface (“Scrim”). Each Video, Camera, or Titles cue you create is then assigned to a surface, and any geometry adjustments you make are relative to that physical surface.

Once a surface is defined, one or more screens can be assigned to it. Each surface may have more than one screen assigned, and each screen may be assigned to more than one surface.

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 separate parts of the surface with no blending.

All your workspace’s surfaces are listed in the Video page of the workspace settings. Each has an Edit button, which opens the surface editor window, and an X button, which deletes the surface. 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.

Auto-created surfaces

When you create a new workspace, QLab will automatically add a surface for each attached display, with that display assigned to the surface. This is for convenience, and intended to allow you to start programming cues quickly in simple setups. You are free to edit and delete these surfaces just as with any surface you create yourself. Any displays connected after a workspace is first created will need to be added manually to a new or existing surface.

Note: This is in contrast to QLab 3.0.x, which treated auto-created surfaces as special cases. Prior to 3.1, QLab would attempt to hide auto-created surfaces when displays were disconnected and create new ones when new displays were plugged in. This was problematic in cases where OS X was unable to differentiate consistently between identical displays.

Rendering pipeline

QLab’s video rendering is a two-step process, with surfaces acting as the intermediate state between steps. First, all the cues playing to a surface render their frames, with any cue geometry and video effects applied, into an image buffer maintained by the surface. Then, that image buffer is used as the source for the final rendering step, in which each screen renders a portion of the full image with edge blending and warping applied.

One important consequence of this two-step rendering process is that surface order takes precedence over cue order. As such, each surface has a layer, much as video cues themselves do. In the first step, each surface renders all the cues patched to it, ordered by cue layer; in the second step, each screen renders every surface to which it’s assigned, ordered by surface layer. If two surfaces occupy an overlapping portion of a screen, a cue on the top surface will show above the cue on the bottom surface, even if the cue layers would seem to indicate otherwise.

Creating and deleting surfaces

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 to create a surface matching the resolution of a single display or partial display, with that display added to the surface’s assigned screens.
3. Select New Multi-Screen Surface to quickly create a surface with a number of regularly arranged screens, such as a multi-projector blended surface or an LCD video wall.

Once a surface is set up, you can make any number of copies of it using the Duplicate button.

To delete a surface, click on the X button in its row in the list of surfaces.

The Surface Editor

Clicking the Edit button next to a surface brings up the surface editor in a separate window.

Many features visible in the Edit window require a Pro Video or Pro Bundle license, and will be disabled if no pro license is installed. The features allowed without a pro license will still function.

Below the header area (composed simply of the surface’s name and dimensions in pixels), the editor window is divided into three columns:

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).

Left column: 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.

To add a screen, click on the + button and select the screen to add. If you have a Pro Video or Pro Bundle license installed, you can also choose partial screens or Syphon. 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 means making that server public, so there is nothing additional happening within QLab. There is, of course, CPU and GPU load associated with whatever application is receiving the frames.

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.

The Reset control points button returns all the perspective/warping controls to their default locations. This applies to the currently selected screen only.

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

Center column: 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 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.

Right column: 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 may be oddly shaped or at an angle to the projector, and have it appear perfectly aligned to the audience.

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 generally best to arrange all the displays on a surface, and split the surface as desired, before adjusting control points.

QLab supports three different types of warping:

• Perspective (the default mode) is useful for simple corner pinning onto a flat surface. Any adjustments made are perspective-correct, meaning that once the corner pins are correctly placed, an image in one part of the surface will appear exactly the same size if moved to a different part of the surface. As a result, splits in Perspective mode surfaces may appear to have discontinuities.
• Linear is more useful for mesh warping, in conjunction with splits. Linear warping guarantees a continuous image across splits, 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 “patches”, each of which has its own set of control points. This opens up the possibility of everything from a surface spanning a single corner, to complex architectural projection mapping.

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 patch 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 1920 by 1080 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 one surface is set to layer 1, and another is set to layer 2, then all cues on the second surface will render on top of all cues on the first 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 a 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.

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.