FxFactory Developer

FxFactory offers two variants of iterators that supplement the built-in iterator patch available with Quartz Composer.

The FxFactory iterator is available as a processor patch and as a consumer patch. At each iteration, it renders a composition that is embedded in the patch. This differs significantly from the built-in iterator, which is a macro patch that dynamically switches between processor and consumer types.

Start by creating an instance of FxFactory Iterator of the consumer or processor type, depending on your design goal:

In its Settings panel, click the “Import…” button to embed the composition that will be executed at each iteration. If you created an iterator of the processor variant, you will also notice extra options that control Render in Image behavior:

Once you've embedded the composition, you can click the “Edit” button to open it inside Quartz Composer. When you save your changes to disk, they are automatically picked up by the parent “FxFactory Iterator”.

Much like built-in iterators, any input or output ports you publish in the embedded composition will appear as inputs and outputs in the “FxFactory Iterator” patch. ¹⁾

Under normal circumstances, all processor patches in Quartz Composer cannot render anything to screen. To enforce this rule, the built-in iterator simply doesn't let you add renderer patches to an iterator that publishes one or more outputs.

The above is not true for FxFactory Iterator (Processor), which allows you embed any composition, including one with renderers.

By default, any renderers embedded in an iterator produce no output image on screen, but you can enable the Render in Image option to capture the outputs of any renderers into separate color and depth buffer images.

The contents of the color and depth buffers are available as output ports in the iterator. This allows you to create a hybrid iterator which computes and renders.

If your composition does not require a depth buffer, it helps to turn on the Disable Depth Buffer option to reduce the amount of video memory used by this patch ²⁾.

You will also notice extra input and output ports are added to the patch after you enable the Render in Image option:

• Pixels Wide and Pixels High let you specify the dimensions of the image generated by this patch. Much like the built-in Render in Image patch, you can assign 0 to generate an image that has the same dimensions as the current rendering destination.
• Bits per component lets you control the bit depth of the image generated by this patch. When Same as parent is selected, the patch will match the bit depth currently used by the parent.
• Multisampling lets you specify that the patch should be rendered using full-scene anti-aliasing. This can be particularly useful if only parts of your composition require multisampling.

• Image contains anything that was rendered by the composition.
• Depth Buffer contains the depth buffer values, as a grayscale image. This output is only available if the Disable Depth Buffer option is off.

There is little penalty from switching between different bit depths or anti-aliasing methods on the fly. FxFactory Iterator uses some caching mechanisms to guarantee consistent performance and minimal use of VRAM.

FxFactory Iterator works more consistently across different versions of Mac OS X, and its ability to capture depth values and render using multisampling makes it a unique and valuable alternative in situations where the built-in iterators and Render In Image patches are found to be lacking.

Quartz Composer sits atop OpenGL, and certain features of this library only work when rendering at 8-bit. FxFactory Iterator may be used to isolate parts of your composition that do not work at 16-bit half-float or 32-bit float by forcing its internal bit depth to be 8-bit integer.

You are required to use the “FxFactory Iterator Variables” patch instead of the built-in “Iterator Variables” patch. You must add this patch to any composition that is embedded and used inside an iterator:

Notice that all outputs are the same as the built-in “Iterator Variables” patch, except the extra “Patch Time” output. This is one substantial way in which our iterator differs than QC: you cannot rely on the value of the built-in “Patch Time” to be correct. To put this graphically, this won't return the correct time:

If you're using any time-dependent patches, you'll have to make their timebase “External”, and hook it up to the “Patch Time” output of “FxFactory Iterator Variables”:

Contrary to the built-in patch, “FxFactory Iterator Variables” will, by default, animate automatically its outputs to help you test the embedded composition:

This “automatic iteration” only happens when the composition is being edited. In the parent's composition, everything will render as normal.

Because embedding compositions and executing iterators can be expensive, “FxFactory Iterator” takes extra measures to make this process faster.

Any time a composition is loaded by an “FxFactory Iterator”, it becomes part of a cache. If a second “FxFactory Iterator” uses exactly the same composition elsewhere in you graph, both iterators will use the same embedded composition. This reduces memory requirements and reduces loading times.

This type of aggressive caching may sometimes break if your graph contains cycles or uses certain patches. To avoid automatic sharing of embedded compositions between multiple iterators, make sure that you don't embed the same composition more than once ³⁾.

Due to the way Quartz Composer works, the canvas will be wiped clean before each iteration while editing an embedded composition.

If you plan on using an iterator with 3D Transformations, it is best to put the 3D Transformation inside the embedded composition.