A full discussion of Quartz Composer and its features is outside the scope of this documentation. The user is strongly encouraged to consult the online resources at the end of this page for further details on Quartz Composer.
Getting Started
Whether you decide to create a new composition from scratch, or modify a plug-in based on an existing composition, this section will illustrate the fundamental techniques that allow a composition to be effectively transformed into an FxFactory plug-in.
You can launch Quartz Composer by selecting "Open Quartz Composer" in the actions menu in FxFactory.
The following picture illustrates Quartz Composer's main user interface elements:
- Patch Library: list of all available patches, which can be dragged onto the workspace. The search box at the top makes it easy to locate patches quickly in the patch library.
- Workspace: the area in the Quartz Composer environment used to assemble patches.
- Inspector: allows you to view and change the values of input ports (e.g. effect parameters), as well as settings for a patch.
- Viewer: previews your composition in real time. The commands under the viewer menu are also available in the toolbar of the viewer window. This toolbar is hidden by default. To display it, click on the white oval button at the top right of the window.
Creating a Quartz composition suitable for plug-in development
The first requirement for turning a Quartz Composition into an FxFactory plug-in is that it renders an image to the screen, using one of the many rendering patches available in Quartz Composer. The simplest such patch is the "Billboard", which renders a 2D image to the screen:
Create an empty composition in Quartz Composer. Add a billboard patch by dragging it from the list of available patches to the desired location on the workspace. By default, billboard patches do not render images at full frame size. To change this, select the billboard patch, bring up the Inspector window and set its blending mode to "Over" and its width to 2 in the "Input Parameters" section:
In the "Settings" section, turn on the "Enable Direct Core Image Rendering" checkbox. This option will cause the billboard patch to generate higher-quality results:
In the next step, add an Input Splitter patch. In the final plug-in, this input splitter will be used to pass the source video from Motion to the composition, so set its type to Image and connect its output to the Image port of the billboard patch:
By default, none of the ports used by a patch are visible outside the scope of the composition. To make the "Input" port of the Input Splitter patch accessible by FxFactory, control-click (or right-click) over the "Input" port and select the "Input" item under the "Published Inputs" menu:
When you choose to publish a port, Quartz Composer gives you a chance to rename it. Please leave the port name unchanged by simply hitting the return key. Once the port has been published, its indicator dot will appear in a solid gray color:
As it stands, the composition now simply acts as a pass-through effect. It takes only one image input and renders it to the screen. To make the effect more interesting, we are going to add a few more patches. Add a "Circular Screen" patch and a "False Color" patch. Select the "Circular Screen" patch, bring up the inspector window and set the "Input Parameters" to the values shown below:
Publish the "Center (X)", "Center (Y)" and "Width" parameters.
Next, select the "False Color" patch, bring up the inspector window and set the "Input Parameters" to the values shown below:
Publish both "Color 1" and "Color 2". Finally, arrange the patches sequentially, and connect them to match the following layout:
Intuitively, the composition just created will take an input image from an external source, process the image using the "Circular Screen" patch, then feed the output of "Circular Screen" to the "False Color" patch. The output of "False Color" is finally rendered on screen using the "Billboard" patch. If you had the Quartz Composer "Viewer" window open until now, you will notice that the window contents have remained empty. This is because without an image passed via the "Input Splitter" patch, the composition has nothing to render.
To test your composition you can simply add an image by dragging it onto the image well, labeled "Input", in the viewer. You can also see the parameters you have published in your composition, and change them to see how they affect the rendered image.
The next step is to create a plug-in based on this composition, so that we can feed it images coming from the clip in the Motion timeline.
Save the composition to the file named "Bull's eye.qtz" via the "Save As..." command under the "File" menu.
Creating the Plug-in using FxFactory
Launch FxFactory and create a new plug-in library by selecting the "New" command under the the "File" menu. Next, click the "New Plug-in from Composition" button on the toolbar in the main library editing interface:
The following sheet will appear:
Choose the Bull's Eye composition you just created:
Name, group and author are all required pieces of information. Enter some values that will differentiate this plug-in from existing ones and allow you to locate it more easily in Motion. The type defines if the plug-in is a generator, filter or transition.
In this case the Bull's Eye composition has one image input and one image output, and is therefore a filter. FxFactory will attempt to choose the correct type for you, based on the composition that you supply.
Click the "Create" button when done. This will return you to the main editing interface, where you can make a few more adjustments in one of the plug-in options groups.
Select the "Parameters" option group. The parameter list should display all the parameters that you have previously published in the Bull's Eye composition:
Select the "Width" parameter. Notice that FxFactory has detected that the "Width" parameter expresses a numeric (floating point) value. By default, FxFactory chooses to display numeric values in Motion via a slider control. You can set all the characteristics of the slider controls using FxFactory. In fact, let's change the slider settings to reflect actual range allowed by the underlying composition:
FxFactory cannot always detect the minimum and maximum values for the slider automatically. In this case, the user may simply go back to the original composition and check the allowed values in Quartz Composer. Among other things, you can decide for every parameter individually if you want it to be displayed, animatable and appear in the dashboard inside Motion.
Notice also that the "Scale value when previewing at reduced resolution" checkbox is on. This checkbox should be enabled for any numeric parameter that expresses a dimension such as distance, radius, border or length. By enabling this feature for the correct parameters, you ensure that the plug-in will preview and render correctly at varying resolutions inside Motion.
Next, select the "Center (X)" and "Center (Y)" parameters and notice that FxFactory is interpreting both as numeric parameters. The default behavior is again to display the parameter in Motion via a slider control. This behavior is correct for the majority of cases, but we know that "Center (X)" and "Center (Y)" represent a two-dimensional location in the input image. Motion provides a better on-screen control for setting point parameters. The next step is to join the two numeric parameters into a single on-screen point control. First select the two parameters, then click the join parameters button at the bottom of the parameter listing:
This will replace the existing Center (X) and Center (Y) parameters with a single point control:
The plug-in is now ready. Choose the "Save As..." command under the "File" menu. Notice that the default saving location is one that will allow you to immediately load the library in Motion. Close the library, and launch Motion next.
Final Result
When you launch Motion, your newly created plug-in library will load at initialization time just like any other plug-in you may have encountered before. If Motion was already running while you created the effect in FxFactory, you may have to quit and relaunch Motion so that the new plug-in may be found.
Once applied, the effect created in this tutorial provides a colorized version of the "Circular Screen" half-toning technique:
A quick look at the "Inspector" window reveals that the parameters mapped in FxFactory are indeed available in Motion for customizing the effect.
Quartz Composer opens far more interesting opportunities to effect artists, but the basic concepts illustrated in this section should serve as a basis for most of your future creations.
See also
Working with Quartz Composer (Apple Developer Connection)
Getting Started with Quartz Composer (MacDevCenter)