FFRend (Freeframe Renderer) is a renderer for Freeframe plugins. It allows you to chain any number of plugins together, automate their parameters using oscillators, and record the output to an AVI file. The input is a video (AVI/MPG), still image (BMP/JPG/GIF), or source plugin.
Most VJ softwares support Freeframe, and can record their output, so what makes FFRend different? FFRend is optimized for content generation, whereas VJ softwares are typically optimized for live performance. The key difference is that FFRend never drops frames, even when your project is too CPU-intensive to be rendered in real time.
It's also possible to perform with FFRend. The user interface is modular, dual-monitor is fully supported, and all parameters and oscillator settings can be controlled via MIDI. Version 2 also supports parallel processing on multi-core CPUs, for greatly improved throughput.
FFRend supports plugin authoring, which means you can export a FFRend project as a Freeframe plugin. The exported plugin is called a metaplugin, because it uses other plugins as components. A metaplugin can be used in any Freeframe-compatible host application, and behaves as if you were running the equivalent project in FFRend.
FFRend is free, open-source software for Windows 2000/XP/Vista/Win7. It includes comprehensive help, an installer, and a simple demo project. If you want to render complex effects at high resolution, using chains of automated Freeframe plugins, FFRend is for you.
New in version 2
FFRend 2 is a near-total rewrite, not an upgrade. The application was completely redesigned from the ground up to take advantage of the parallel-processing capabilities of today's multi-core CPUs.
Major differences
Minor differences
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA.
Requirements
Recommended:
Intel Core i7 920 Nehalem 2.66GHz Quad-Core Processor
ASUS Rampage II GENE LGA 1366 Intel X58 Micro ATX Motherboard
Crucial 6GB (3 x 2GB) 240-Pin DDR3 SDRAM DDR3 1066 Memory
OCZ ModXStream Pro OCZ700MXSP 700W Modular Power Supply
Western Digital Caviar WD1001FALS 1TB 7200 RPM SATA Hard Drive
EVGA 896-P3-1257-AR GeForce GTX 260 Core 216 896MB Video Card
Windows XP SP2
DirectX 9
1024 x 768 / 32-bit color
Minimum (version 1):
Pentium III 833MHz
256MB RAM
Windows 2000 SP4
DirectX 8.1
640 x 480 / 16-bit color
Installing
Installing for the first time:
FFRend is distributed as a .zip file. Unzip the distribution file, using WinZip or an equivalent program, and then double-click on FFRend.msi to launch the installer. The installer is about as simple as an installer can be: just keep hitting "Next." Note that on the "Select Installation Folder" page, you have the option to install for all users, or only for the current user.
Upgrading a previous installation:
Note that double-clicking FFRend.msi won't work: you will get the message "Another version of this product is already installed".
It is possible to have both versions 1 and 2 installed on the same machine. However, uninstalling either version may cause the other to fail during recording, with the message "Can't create BmpToAvi filter. Class not registered". To fix this, rerun the installer for the remaining version, and select "Repair".
Uninstalling
To uninstall FFRend, use Add/Remove Programs in the Control Panel, or double-click on FFRend.msi and select the "Remove" option, or in the Task Bar, select Programs/FFRend/Uninstall.
Demo project
FFRend's binary distribution includes a simple demonstration project, called DemoBall.ffp. You'll find it in the same folder as the application (typically C:\Program Files\FFRend). DemoBall loads a Freeframe plugin (FFSrcPlug.dll, also included) which displays a bouncing ball. The plugin has a single parameter, the ball speed. This parameter is automated, using a ramp down waveform, so that the ball gradually slows down and then suddenly speeds up again.
A Freeframe plugin processes video frames. FFRend allows you to load multiple plugins at once. The plugins form a chain, i.e. each plugin takes its input from the previous plugin's output. By default, video frames flow through the chain from left to right. In this case, the order in which the plugins appear is significant, because it determines the order in which they process video; reordering them can have a dramatic effect on the output.
It's also possible to create an explicit routing that overrides the default left-to-right signal flow. This is essential if you're using multi-input plugins; see Patch Bay.
Input video
The plugin chain requires an input, i.e. a source of video frames to process. The input to the plugin chain comes from a video file (AVI/MPG), a still image (BMP/JPG/GIF), or a special type of Freeframe plugin, called a source plugin. Source plugins differ from effect plugins, in that they don't take any input, they only create output.
Note that FFRend needs AviSynth to play MPEG files. If you try to play an MPEG without AviSynth, FFRend displays an error message asking you to verify that AviSynth is correctly installed. AviSynth is free software; you can download it from http://avisynth.org.
To use an input video or image file, choose File/Video/Open, or drag the file from Windows Explorer and drop it onto FFRend's main window, or drag it from the File Browser. To use a source plugin, load it into the plugin chain, in the same way as an effect plugin.
Note that you must have a video or image file open, or have a source plugin in your plugin chain, otherwise you won't get any output. If you have both a video/image and a source plugin, the source plugin wins: the video/image remains hidden unless you bypass (or delete) the source plugin.
Plugin slots
A slot is a container into which a Freeframe plugin can be loaded. Plugin slots are represented by tabs along the top of FFRend's main window. To insert a slot, use Edit/Insert, or the Ins key. To delete a slot, use Edit/Delete, or the Del key. Plugins can also be inserted and deleted using the plugin context menu, which is displayed when you right-click on a tab.
Only one plugin slot can be viewed at a time. This slot is referred to as the selected plugin. To select a slot, left-click on its tab.
A plugin slot can be cut or copied to the clipboard, and then pasted to a different project, or elsewhere within the same project, using the standard Edit commands, or the plugin context menu.
Loading plugins
Before a plugin can process frames, it must first be loaded into a slot. Once a plugin is loaded, it displays its parameters and allows you edit or automate them.
The simplest way to load a plugin is via Plugin/Load or Ctrl+L. The command displays a file open dialog; browse for the desired plugin, and press OK. The plugin is loaded into the selected slot. Note that if the selected slot already contained a plugin, the new plugin replaces it.
To load a plugin into a specific slot, you can also right-click on the slot's tab, and select Load from the plugin context menu.
Plugins can also be loaded via drag and drop from Windows Explorer or from the File Browser. This method allows you to load multiple plugins at once. Note that with this method, existing plugins are not replaced; empty plugin slots are inserted automatically. If you drop on a slot tab, insertion occurs at that position. If you drop elsewhere, insertion occurs at the selected slot.
To unload a plugin, use Plugin/Unload, or choose Unload from the plugin context menu.
Reordering plugins
Unless you create an explicit routing, the order in which plugins appear in the plugin chain determines the order in which they process video. The plugins can be reordered at any time, without disrupting their states, via drag and drop. To move a plugin, left-click on its tab, and while holding down the left mouse button, drag the cursor horizontally. The cursor changes, to indicate that you're in drag mode. To drop the plugin, position the cursor over the desired tab and release the left mouse button. The plugin is moved to the new location, and the output is affected immediately.
Monitoring plugins
The Monitor control bar normally displays the output of the entire plugin chain (i.e. the same image as the output window), but it can be configured to display the output of a specific plugin instead. This feature lets you examine any intermediate stage in your plugin chain, in a nondestructive way, without affecting FFRend's output. It's mostly useful for debugging, but it can also be used for previewing.
Before you try to monitor anything, make sure the Monitor bar is visible. To show or hide the Monitor bar, use View/Monitor or Shift+N. To monitor a plugin, select it, and then use Plugin/Monitor or F8. A monitor icon is displayed in the plugin's tab, to remind you that the monitor source was changed. To return to monitoring FFRend's output, choose Plugin/Monitor again. You can also control the monitor source via the Plugin or Patch Bay context menus, or the Monitor bar's context menu.
Bypass and solo
A plugin can be temporarily bypassed, i.e. disabled so that it has no effect on the output. The bypass state is a toggle: to disable or reenable the selected plugin, use Plugin/Bypass, or choose Bypass from the plugin context menu.
It's also possible to solo a plugin, i.e. bypass all plugins except the selected plugin. This can be useful for isolating problems. Solo is also a toggle: to enter solo mode, use Plugin/Solo, or choose Solo from the plugin context menu. Choose solo a second time to exit solo mode; this restores the bypass settings that were in effect when solo mode was entered.
Note that Bypass works in solo mode; this allows you to solo a plugin, and then add the other plugins back into the chain one at a time, by un-bypassing them.
Also note that in version 2, bypass/solo doesn't change the routing, therefore it's possible to get unexpected results.
Patch Bay
As of version 1.3, FFRend supports multi-input plugins. FFRend's default signal flow (linear from left to right) is adequate for single-input plugins, but for multi-input plugins, it's necessary to create explicit connections. This is typically done using the Patch Bay control bar. To show or hide the patch bay, use View/Patch Bay or Shift+P.
The patch bay includes a panel for each plugin, and each panel contains one or more source drop-lists, depending on how many inputs the plugin has. The drop-list begins with a default option, followed by a list of the plugins in your project, each of which is a potential input source. A check appears next to the currently connected source. To connect the input to a source, select the source in the drop-list. To break the connection and restore the default signal flow, select <default>.
Connections can also be made using the Plugin/Input popup menus, or the plugin context menu (displayed when you right-click on a plugin tab), but the patch bay is more convenient, mainly because it allows you to see all of your connections at once. The patch bay also lets you quickly change the order of the plugins, by dragging them within the patch bay. Each patch bay row also has an Enable checkbox; unchecking it bypasses the corresponding plugin.
The overall layout of connections between plugins is known as the routing. Routing doesn't have to be entirely explicit: it's fine to have a mix of explicit and default routing. Default routing requires less setup, and can be changed by simply reordering the plugins. One strategy is to only use explicit routing when necessary. Note that if you replace a plugin with a different one via Plugin/Load, FFRend preserves the existing routing as much as possible; this allows you to audition plugins without having to redo your connections.
It's possible to connect a plugin to itself, resulting in feedback. As with analog feedback, the output may saturate to white or black, or converge on a steady state, or may not get started without a seed, e.g. a video clip. Automating some of the effect parameters may help prevent a steady state from developing. More complex feedback can be generated by using longer signal loops involving more effects, and by using a mixer plugin to adjust the amount of feedback. For example, in the following setup, the signal flows from Chromium to Mixer, and then from Mixer to PanSpinZoom and back into Mixer; the more Mixer favors input B, the greater the amount of feedback.
Note that in version 2, certain feedback cases can cause the engine to stall. These cases are esoteric and generally involve multiple feedback routes to the same plugin.
| Plugin | Input | Source | Comments |
|---|---|---|---|
| Chromium | <default> | video clip or whatever | |
| PanSpinZoom | Mixer | feedback loop | |
| Mixer | A | Chromium | routed over PanSpinZoom |
| B | PanSpinZoom | more B = more feedback |
Freeframe plugins are available from various sources on the net, including the Freeframe web site, http://freeframe.sourceforge.net/. Paradoxically, not all Freeframe plugins are free, but some of the best ones are. The author recommends the following freeware plugins:
A Freeframe plugin can have any number of adjustable settings which affect its behavior; these settings are called parameters. Freeframe parameters are normalized, i.e. they have a fixed range (from 0 to 1). When a plugin is loaded, FFRend determines what parameters it has, and then automatically creates an appropriate user interface for displaying, editing or automating them.
Editing parameters
FFRend can display the parameters of only one plugin at a time, referred to as the selected plugin. Only the selected plugin's parameters can be edited; to edit the parameters of a different plugin, you must select it first, by left-clicking its tab.
For each of the selected plugin's parameters, FFRend displays a row in its main window. Each parameter row includes the following columns:
The remaining columns are used for automating parameters. Note that a plugin may not have any parameters, in which case no parameter rows will be displayed when that plugin is selected.
Automating parameters
FFRend provides a way of making a parameter change by itself. This is referred to as automating the parameter. While a parameter is being automated, its slider and value are updated continuously, so that you can watch the parameter change.
An automated parameter is controlled by a low-frequency oscillator (LFO), using a technique known as modulation. Since each parameter has its own oscillator, multiple parameters can be modulated at once, each in a different way. An oscillator generates an endlessly repeating pattern, determined by its waveform, amplitude, and frequency. The waveform and frequency are specified as explained below. The amplitude defaults to the maximum range of the parameter (0 to 1), but it can also be limited, using a modulation range.
An automation can be resynchronized by left-clicking in the parameter's slider track. The slider thumb jumps to the cursor position, and automation continues from that point, though not necessarily in the same direction. To synchronize all of your automations at once, use Edit/Sync Oscillators.
Oscillator waveforms
A Freeframe parameter ranges from 0 to 1, and when a parameter is automated, its value normally traverses this entire range. Sometimes it's desirable to limit the value to a smaller range, called a modulation range. The range determines the amplitude of the modulation.
A parameter's slider has an unusually wide, open track, which is used to display the modulation range. The range is represented by a dark blue rectangle located within the slider track. During automation, the slider thumb (the part that moves) is confined to this rectangle.
A modulation range can be created in various ways. One method uses the slider's current position to set the range. Move the slider thumb to where the range should start, and choose Edit/Modulation Range/Set Start, or press Ctrl+Home. Now move the slider thumb to where the range should end, and choose Edit/Modulation Range/Set End, or press Ctrl+End. To remove an existing range, choose Edit/Modulation Range/Remove.
It's also possible to create or edit a modulation range numerically, using a dialog. To show the dialog, use Edit/Modulation Range/Edit. The dialog displays the current range, and allows you to edit it. To remove an existing range, set either the start or the end to −1.
The commands described above are also accessible via context menu. Note that to display the context menu, you must right-click on the parameter's name, NOT on its slider; right-clicking on the slider is reserved for additional shortcuts, which are explained below.
Shortcuts for creating a new range:
Shortcuts for editing an existing range:
The entire plugin chain, including all plugin parameters and their automations, can be saved in a single document, called a project. To save your work as a project, use File/Save or File/Save As. To open an existing project, use File/Open. To start a new project, use File/New.
A project doesn't actually contain plugins; instead it contains links to plugins. Consequently, if plugins are moved or renamed, broken links can occur; see missing files. The project also includes a link to the input video if applicable. In general all settings are stored in the project, except for those found in the options dialog, which are stored in the registry.
Master speed
The Master toolbar allows you to affect the speed of all your automations at once. The toolbar contains a scaling percentage that's applied to your oscillator frequencies. If the scaling percentage is 100 (the default), the automations are unaffected; at 200 they're double speed, and at 50 they're half speed. To display or hide the toolbar, use View/Master or Shift+M. To change the master speed, set the desired percentage, via either the slider or the edit box.
If the CPU is overloaded while you're developing a project, the actual frame rate may be less than the ideal, which means your automations may seem slower than they actually are. You might not discover this problem until you record the project and watch the output video. If this situation occurs, you can use master speed to slow down your automations proportionally, instead of editing them one by one.
File Browser
The File Browser control bar allows you to navigate your files without using the File Open dialog or Windows Explorer. To show or hide the file browser, use View/File Browser or Shift+F. The browser has separate tabs for your Projects, Plugins and Clips, and remembers the current folder and view settings for each tab. To open a file, double-click its name, or select its name and press Enter, or drag the name onto the main window. The Plugins tab allows multiple selections, but the other two don't.
Note that if you drag plugins onto the plugin tabs, or onto the patch bay, they're inserted into the plugin chain at the drop point, i.e. it matters which plugin tab or patch bay row the cursor is over when you release the left mouse button. If you drag plugins elsewhere within the main window, they're inserted at the selected plugin.
The file browser supports five views: Icons, Small Icons, List, Details, and Thumbnails. To change the view, use the browser's context menu, which is displayed when you right-click anywhere within the browser except on a file name. Right-clicking on a file name brings up the file's context menu instead.
Which view you should use depends on how you dock the browser to the main window. In the default layout, it's docked vertically on the right, but if you prefer to dock the browser horizontally along the bottom, the List view lets you see more files at once. In the Details view, you can sort the files in various ways, using the Explorer-style clickable column headers. In the other views, use the context menu's Arrange option to sort the files. The Details view also supports resizing and reordering the columns.
The Thumbnails view is useful for selecting clips visually. Note that video clips will have thumbnails under XP but not under W2K. Thumbnails are created on demand whenever you browse a folder in Thumbnails view. By default, thumbnails are cached on disk, so they only need to be created once, though you can disable this feature via the Options dialog. Creating thumbnails can be CPU-intensive, so if you're performing live, create your thumbnails beforehand if possible.
FFRend's docking behavior is typical for Windows applications. If the bar is docked, double-clicking on its gripper (the two parallel lines) floats it. If the bar is floating, double-clicking on its caption docks it again. Bars can be resized while docked or floating. To move a bar to a new docking position, drag it by its gripper. To move a floating bar and prevent it from docking, drag it by its gripper while holding down the Ctrl key.
Missing Files
A project contains links to plugins. If a project's plugins are moved or renamed, broken links can occur. Broken links must be repaired before the project can be opened. If you try to open a project with broken links, FFRend displays the Missing Files dialog, which gives you the following options:
Warning: In all of the above cases except "Cancel", it's possible to open the project with plugins still missing. If you save the project in this situation, the missing plugins are permanently deleted from the project. To avoid doing this accidentally, save the project under a new name (using File/Save As) before proceeding.
Replace Files
If "Open Dialog" is selected in the Missing Files dialog, the Replace Files dialog is displayed. It lists the name and current status of each missing plugin, and gives you the following options:
Warning: If plugins are still missing when you press "OK", they are removed from the project. If you save the project in this situation, the missing plugins are permanently deleted from the project. To avoid doing this accidentally, save the project under a new name (using File/Save As) before proceeding.
FFRend can record the output of your plugin chain to an AVI file. The AVI can be compressed or uncompressed. If it's uncompressed, there's no 2 GB limit; the AVI is limited is only by available disk space.
To create a recording, choose View/Record or press Ctrl+R. A file dialog is displayed; select a folder and filename for your recording, and press OK to continue. Next, the Record dialog is displayed. This allows you to specify the recording's length, frame size, and frame rate. Again, press OK to continue. Finally, the Video Compression dialog is displayed. This allows you to select and configure a video compressor. Press OK to begin recording.
You may find it convenient to start a recording while paused, to avoid missing the first few frames of your project. If you're trying to make an exact duplicate of a previous recording, and your project makes any use of randomness, you may also want to restart FFRend before each recording, so that the random seed is always freshly initialized.
Note that you have the option to defer the recording, instead of starting it immediately. To do this, check the Record dialog's "Don't run this job now; add it to job control instead" checkbox. You can queue any number of jobs, and then run them all at once; see Job Control.
Record dialog
| Custom | Lets you enter the desired length in the edit box. The Time/Frames radio buttons determine the input format. If Time is selected, enter a time in hh:mm:ss format; if Frames is selected, enter a frame count. |
| Unlimited | Records indefinitely, i.e. until you stop the recording manually. |
| Use AVI length | Sets the duration to the exact length of the input AVI file, and also automatically rewinds the AVI file at the start of the recording. Note that you must have an AVI file open, otherwise this option is disabled. |
When you set up a recording, you can choose to defer it instead of starting it immediately. Deferred recordings are called jobs, and they're stored in a job queue. You can queue any number of jobs, and run them all at once while you're doing something else. This is known as batch processing.
The job queue is managed via the Job Control dialog; to show the dialog, use File/Job Control, or press F4. The dialog's layout should look very familiar to users of VirtualDub. The dialog contains a list, each row of which corresponds to a queued job. The columns are described below.
| Name | The job name. | |
| Source | The source file, i.e. the name of the project from which the job was created. | |
| Dest | The destination file, i.e. the name of the output video file. | |
| Start | When the job started. | |
| End | When the job ended. | |
| Status | Waiting | The job is ready to run. |
| Postponed | The job is not ready to run. | |
| In Progress | The job is currently running. | |
| Aborted | The job was canceled by the user. | |
| Failed | The job stopped due to an error. | |
| Done | The job completed successfully. | |
To start batch processing, press the Start button. To cancel processing, press the Abort button. To cancel the current job, but continue processing, press the Skip button. Jobs are processed in the order in which they appear in the queue, and only jobs with a status of Waiting are processed.
Editing the queue
The job queue can be edited at any time, even during processing. The only restriction is that you can't delete or change the status of a job while it's in progress. The editing commands are as follows:
To change the status of multiple jobs at once, use these commands from the Job Control dialog's Edit menu:
To delete all completed jobs, Use Edit/Delete done jobs. To delete ALL jobs, use Edit/Clear list. The job queue can be saved to a file, or restored from a previously saved file, via File/Save job list and File/Load job list. To shutdown your computer after all jobs are completed, select Options/Shutdown when finished.
Job independence
Once a job is queued, it's completely independent of the project from which it was created. This is possible because the queued job contains a copy of the project data. Any subsequent changes made to the project file have no effect on the queued job. The project file can even be renamed or deleted. Note however that the job still depends on the project's plugins and input video. Be careful not to rename or delete plugins or clips referenced by a queued job, otherwise the job will fail.
A queued job also contains a snapshot of all application settings that could affect the job's behavior, including those found in the Options dialog and Record dialog. A job runs with the settings that were in effect when the job was queued, NOT the current settings. For example, if the engine frame size was 640 x 480 when a job was queued, that job always runs at 640 x 480, regardless of the current frame size.
Exporting bitmaps
Any frame of FFRend's output can be exported as a bitmap file. The bitmap's size will match the current engine frame size. Only 24-bit color is supported. To export a bitmap, choose File/Export or press Ctrl+E, select a folder and filename for the bitmap, and press OK.
Export list
Sometimes you'll make a low-resolution recording, and then discover that certain frames would make nice still images, if only they had higher resolution. Why not just re-record the entire project at higher resolution? Because this might require a very large amount of disk space, especially since for making still images, you would prefer to use uncompressed video.
Instead of re-recording the entire project, you can export a list of specific frames. To do this, you must first create a frame list. This is simply a text file, containing the frame numbers of the still images you're interested in, as integers, one per line. Now set the desired resolution, enter pause mode, reload your project, and choose File/Export List. A file dialog is displayed; select your frame list, and press OK. FFRend regenerates the project, saving the specified frames as bitmaps, and throwing the rest away.
Note that certain plugins may not behave exactly the same way at different resolutions; you may need to compensate their parameters. Also note that if your project uses randomness, you may not be able to repeat the exact same sequence of frames unless you restart FFRend each time you load your project; see also random seed.
Pause
FFRend's processing can be paused at any time, using Window/Pause, or by pressing the Space bar. To resume processing, use Window/Pause or the Space bar again. While in pause mode, you can step forward frame by frame, via Window/Step, or Shift+Space.
Before you can control FFRend with MIDI, you must first select a MIDI device. Then you must assign MIDI messages to the things you want to control, using the MIDI Setup dialog. To show or hide the dialog, use View/MIDI Setup or Shift+I. MIDI assignments can be created via editing, or learned.
Things to which MIDI can be assigned are called targets. The most common MIDI targets are plugin parameters, or oscillator settings, such as modulation frequency. The list of available targets varies, depending on which plugins are loaded.
The MIDI Setup dialog contains tabbed pages of rows, much like the main window. There's a page for each plugin, and its rows correspond to the plugin's parameters. Each row lets you assign MIDI to a parameter's properties, which include the parameter itself, and its oscillator settings. Use the drop-list in the upper left corner of the dialog to select which property you're assigning to. If you just want to control parameters, not their oscillators, leave the drop-list set to "Parameter".
Put another way, the parameter pages form a three-dimensional matrix of MIDI targets, in which the axes are plugins, parameters, and properties. The pages correspond to plugins, the rows correspond to parameters, and the drop-list selects a property.
The dialog also includes three additional pages: the Plugin page, the Misc page, and the Metaparam page. The Plugin page is for properties that occur once per plugin, e.g. Bypass; the page contains a row for each plugin. The Misc page is for system-wide properties, e.g. Master Speed. The Metaparam page lets you assign MIDI to metaparameters.
MIDI editing
MIDI assignments can be created and edited using the controls in each row of the MIDI setup dialog. The controls are described below. To make assignments this way, you must know which messages your device sends, and on which channels. MIDI assignments can also be learned, in which case you don't need to know these details.
Note that a given MIDI message can only be assigned to one target at a time, though you can work around this restriction by using metaparameter groups. When you assign a message, if that message is already assigned to a different target, the previous target automatically (and silently) "loses" the message. Specifically, the previous target has its Event type set to "OFF".
Range lets you make a trade-off between the precision and magnitude of a MIDI controller: making Range smaller allows finer adjustment, but reduces the controller's effect. Range can be negative, in which case the controller's effect is inverted.
| OFF | No message is assigned to the target. |
| CTRL | A continuous controller message is assigned to the target; the controller edit box specifies the controller number. |
| NOTE | A note is assigned to the target. In this case the controller edit box displays and understands MIDI note numbers, e.g. F#4. Pressing the note toggles the target, i.e. flips it back and forth between 0 and 1. Releasing the note has no effect. Notes are useful for controlling switches. |
| PITCH | The pitch bend message is assigned to the target. In this case the controller edit box is ignored. |
Assigning MIDI messages via editing requires you to know which messages your device sends, and on which channels. FFRend can also "learn" the MIDI assignments, in which case you don't need to worry about those details. To use "learn" mode, do the following:
If you close the MIDI setup dialog with the "Learn" box checked, it will still be checked when you reopen the dialog, but no target will be selected. This helps prevent you from accidentally trashing your assignments.
This option allows you to specify the size of the video frame that's passed along your plugin chain. This size effectively determines the rendering resolution. Use the drop list to choose a standard frame size; for other sizes, choose "Custom", and then enter the desired width and height in pixels.
The engine frame size can differ from the input video frame size, in which case the input video is resized to fit. Note that this may cause distortion, which you can avoid by matching the frame size to the input video whenever possible.
The engine frame size can also differ from the output window size, e.g. you could render at 320 x 240 but view the output at 1024 x 768. The output image is generated post-rendering, so the size of the output window doesn't affect rendering quality.
Changing the frame size reinitializes any currently loaded plugins. This may cause glitches in the output, so changing the frame size during a performance is not recommended.
As the resolution increases, more CPU time is required to render each frame. Large frame sizes may cause FFRend to fall behind and no longer be in real time. When you're recording a finished project, staying in real time usually isn't a concern. During development, however, staying in real time is preferable, because otherwise it's hard to judge the speed of your automations.
Consequently, it can make sense to develop your projects at a low resolution, and then record them at a higher resolution. One problem with this approach is that your plugins may not behave exactly the same way at different resolutions. For example a plugin could have a parameter that's specified in pixels. Such a parameter would have to be compensated for changes in frame size.
While FFRend doesn't impose any upper limit on frame size, unfortunately the same can't be said for Freeframe plugins. Many plugins behave unexpectedly above a certain frame size. The limits vary, and can only be determined by trial and error. Most plugins can handle at least 1024 x 768, but above that, expect surprises.
Frame rate
This option specifies the ideal rate at which video frames should be processed and displayed, in frames per second (FPS). The actual frame rate can differ from the ideal. Both the ideal and actual frame rates are displayed in the status bar.
The actual frame rate is an approximation, and may fluctuate slightly around the ideal, but if it's consistently wrong, FFRend is not in real time. Note that FFRend NEVER drops frames, no matter how incorrect the actual frame rate is. Frame rate errors can be divided into two types: timer-related, and load-related.
Timer-related errors are linked to the way timing is done in Windows, which makes some frame rates easier to approximate than others. Timer-related errors are identified by the fact that they occur even when the CPU is idle. They can often be reduced by using a multimedia timer.
Load-related errors occur when the time required to process a frame exceeds the time available. The time available is a function of the frame rate, e.g. at 25 FPS, each frame must be processed in 1/25 of a second or less. If reducing the frame size or simplifying your plugin chain helps, the problem is load-related. For more information, see performance.
Color depth
This is the color depth of FFRend's rendering engine, in bits per pixel. Only plugins that support the selected color depth can be loaded. For optimal results, the selected color depth should match the color depth of the display device. If it doesn't, FFRend warns you and gives you an opportunity to fix it. Ignoring this warning may cause the output window to show garbled data.
Timeout
This is how long FFRend's rendering engine will wait for a plugin to output a frame, in milliseconds. If a plugin takes longer than this, the engine stalls. If you're using a very high resolution, or running on a weak machine, you may need to increase the timeout to prevent the engine from stalling. A reasonable timeout for a given frame rate can be calculated as follows:
Timeout = 1000 / FrameRate × 2
The engine can also be stalled by certain types of routing, typically involving multiple feedback paths to the same plugin. In such cases, the timeout determines how long the engine will wait before stalling.
Lock frame rate
Unchecking this option allows the engine to run as fast as it can, instead of being limited to the selected frame rate. In full screen mode, the engine will render at the refresh rate of the display device, assuming the engine can keep up. In windowed mode, the engine can render even faster than the display refresh, and is limited only by CPU throughput.
In full-screen mode, rendering exactly one frame per vertical trace gives the smoothest appearance. This can't be achieved by simply setting the frame rate equal to the display frequency, because the engine's frame timer isn't synchronized with the vertical trace. However, unlocking the frame rate CAN achieve one frame per vertical trace, because in this case the engine synchronizes directly to the display hardware, instead of using a timer.
Unlocking the frame rate can potentially cause automations and video clips to speed up. If this is undesirable, you can compensate for it by adjusting the master speed and/or the playback speed of your clip player(s).
During recording, unlocking the frame rate allows FFRend to record faster than real time. This can potentially save a considerable amount of time. Note that the apparent speed-up of automations and video clips has no effect on the recorded output.
Multimedia timer
The standard Win32 timer provided by Windows is unable to accurately achieve many common frame rates. For example under XP, if the frame rate is set to 25 FPS, you'll actually get 21.33 FPS, which is a considerable difference. This may not matter if you're recording at high resolution, because you're probably not in real time anyway, due to CPU overload. It's more likely to be a problem when you're previewing your work at low resolution. You want a correct frame rate when you're previewing, because otherwise you won't get an accurate sense of how fast your parameter automations are.
To make the frame rate more accurate, check the "Use multimedia timer" option. Note that this is a trade-off, because a multimedia timer uses significantly more CPU time.
| Achievable frame rates | ||
|---|---|---|
| Win32 timer | Multimedia timer | |
| 2000 | 100, 50, 33.33, 25, 20, 16.67, etc. | 100, 90.91, 83.33, 76.92, 71.43, 66.67, 62.5, 58.82, 55.56, 52.63, 50, 47.62, 45.45, 43.48, 41.67, 40, 38.46, 37.03, 35.71, 34.48, 33.33, 32.26, 31.25, 30.3, 29.41, 28.57, 27.78, 27.03, 26.32, 25.64, 25, 24.39, 23.80, etc. |
| XP | 64, 32, 21.33, 16, 12.8, etc. | |
A frame rate is normally expressed as a frequency, i.e. 25 FPS is equivalent to 25 Hz. A Windows timer is specified via its period, which is the inverse of the frequency. A timer has a property called granularity, which you can think of as its coarseness. Only timer periods that happen to be multiples of the granularity are supported. Other timer periods are rounded to the nearest multiple of the granularity. This won't make much difference if the granularity is fine compared to the period you want: e.g. a granularity of 10 ms might be acceptable if you're trying to wait a minute, or an hour. Unfortunately the granularity of a Win32 timer is coarse compared to most common frame rates, and worse still, it varies by Windows version.
Under Windows 2000, the timer granularity is 10 ms. If you ask for 25 FPS, you're in luck, because the period is 1/25 = 0.04 or 40 ms, which just happens to be a multiple of the timer granularity. On the other hand, if you ask for 30 FPS, the period is 1/30 = 0.033 or 33 ms, which is definitely not a multiple of 10 ms. The period therefore gets rounded up to the nearest multiple of 10, i.e. 40 ms, so you still get 25 FPS, even though you asked for 30 FPS. Not good.
You might wonder why 33 was rounded up, instead of down, since 33 is closer to 30 than 40. It turns out that timer periods are always rounded up in Windows 2000, whereas in XP they're rounded up or down, depending on which granularity is nearest.
Under XP, the timer granularity is 15.625 ms. If you ask for 25 FPS, the period (40 ms) gets rounded up to the nearest multiple of 15.625 ms, i.e. 46.875 ms (15.625 * 3), giving you a frame rate of 1/.046875 = 21.33 FPS. If you ask for 30 FPS, the period (33 ms) gets rounded down to 31.25 ms (15.625 * 2), giving you a frame rate of 1/.03125 = 32 FPS, which still isn't too helpful.
In summary, with a Win32 timer, 30 FPS is not achievable under Windows 2000, and neither 25 nor 30 FPS are achievable under XP. In contrast, a multimedia timer has one millisecond granularity under both 2000 and XP, which allows reasonable approximations of most common frame rates, though at the cost of increased overhead.
MIDI device
This option allows you to select a MIDI device. The list of devices varies, depending on what MIDI hardware is installed. If your PC doesn't have a MIDI device, the only option is "No MIDI input", which disables FFRend's MIDI support.
The default value is "No MIDI input", which means that in order to use MIDI, you must select a MIDI device at least once. You'll also need to assign specific MIDI messages to FFRend's functions, using the MIDI Setup dialog.
If you're using a USB MIDI interface, it's better to connect it to the PC before launching FFRend. If you launch FFRend while the interface is disconnected, your device selection will be lost. If you connect the interface while FFRend is running, it won't automatically appear in the device list; you must press the Refresh button to refresh the device list. If that doesn't work, exit FFRend, reconnect the interface, re-launch FFRend, and select the device.
Random seed
FFRend uses random numbers for some of its oscillator waveforms. This option allows you to control the seed value that's used to generate random numbers. You can specify a particular value, or you can use the system time, by checking the "Use time" checkbox, in which case no two runs of the program will generate the same random numbers.
FFRend's random numbers aren't truly random, in the way that tossing a coin is random; they're actually pseudorandom. Pseudorandom numbers form a deterministic sequence, which repeats eventually, but appears random enough to be useful. A pseudorandom sequence evolves from an initial value, called the random seed.
If the random seed is a fixed value, every time the program is run, it generates the exact same sequence of pseudorandom numbers. This can be good or bad, depending on the situation. If you want true randomness, the solution is to have the program use a different seed each time it runs. In practice this is accomplished by using the system time as the seed. This works because the system time is unlikely to ever be the same for any two runs of the program.
In some cases true randomness may not be what you want however. For example, suppose you create a project that does something you like, and you want it to do the exact same thing again in the future, e.g. so that you can make a recording of it. If your project makes any use of randomness, and you were using the system time as a random seed, you're out of luck. Your project will never do exactly the same thing again. This might be a good reason to not use the time as a seed.
View frequency
This option specifies the rate at which the user interface is updated, in Hertz. This rate is completely independent of the engine's frame rate. It controls the smoothness of slider motion for automations, the refresh rate of the Monitor bar, and the speed of the History and Queues views.
History size
This option determines the size of each plugin's event buffer in the History view. To capture a longer history, increase this size. The size is in measured in events. Since there are two events per frame, a size of 256 is enough for 128 frames. Memory usage is 8 bytes per event, times the number of plugins.
Monitor quality
This option allows you to adjust the trade-off between performance and quality in the monitor bar. For better performance, select "fast". For better quality, select "smooth". The performance impact of "smooth" mode can be significant for large frame sizes.
Save warning
If the current project has been modified, opening a different project normally causes the application to display a Save Changes warning dialog. In some cases this behavior may be undesirable, e.g. during a live performance. To suppress the warning, uncheck the Save Warning checkbox.
Undo levels
This option allows you to set the number of undo levels. For unlimited undo, check Unlimited; otherwise, uncheck it, and enter the desired number of levels in the edit box. To disable undo, set the number of levels to zero. By default, undo is unlimited. The undo history is cleared whenever you start a new project or opening an existing one. Note that unlimited undo can consume a significant amount of memory over time.
Global plugin
This option was removed in version 2.
The global plugin option allows you to apply a post-process to all of your existing projects without editing the projects. This can be useful during a live performance, e.g. you might want to adjust the brightness/contrast globally, or display your projects through a matte. When you open an existing project, the global plugin is automatically appended to the plugin chain. The global plugin is NOT included when you save the project.
To set a global plugin, open the Options dialog, go to the Global plugin group, and press the Browse button. A file dialog is displayed. Select a plugin, and press OK. The selected plugin is added to the drop list. Press OK again to save your changes and close the Options dialog. Now open an existing project, and the global plugin should appear at the end of the plugin chain. Note that nothing happens until you open a project; selecting a global plugin has no effect on the current project.
The drop list contains the most recently used global plugins, so that you can select one of them quickly without browsing. To disable the global plugin, select <none> in the drop list. Again, note that you must open a project before global plugin changes take effect.
If you edit the global plugin's parameters, the edits persist until you select a different global plugin, or exit the application; the global plugin's state is not affected by opening projects. The same is true if you bypass the global plugin, or automate its parameters.
It is possible to apply multiple effects at once, even though there's only one global plugin. To do this, encapsulate the desired effects in a metaplugin, and then select the metaplugin as the global plugin.
Thumbnails
The File Browser supports a Thumbnails view for selecting clips visually. The thumbnails can be created in various sizes. To change the thumbnail size, select a different size in the "Thumbnail Size" drop list.
Thumbnails are created on demand whenever you browse a folder in Thumbnails view. By default, thumbnails are cached on disk, so they only need to be created once; to disable this feature, uncheck the "Cache thumbnails" checkbox.
FFRend stores thumbnails in the folder to which they apply, in a database file. The database files are named according to a specific convention, e.g. for 96 x 72 in 32-bit color, the database name is ckThumbs96x72x32.db.
Run while loading project
This advanced engine option controls whether the current project should continue to run while a new one is being loaded. It's enabled by default. Enabling this option reduces downtime (i.e. frozen output) while switching between projects, but at the cost of increased memory usage: during the transition, sufficient memory must exist to accommodate the current project's Freeframe instances and frame buffers, plus the new project's Freeframe instances. Disabling this option conserves memory, which can be useful when working with large frame sizes.
Frame memory
This advanced engine option limits the amount FFRend can use for its frame buffers. This is helpful when working with large frame sizes. By default the engine optimizes for speed over memory conservation, i.e. it allocates enough frame buffers for the worst possible case, regardless of memory limits. The engine can function with considerably less memory, though allocating too little may reduce throughput, or cause the engine to stall. Note that this option has no effect on memory allocated by Freeframe plugins.
The limit is specified in megabytes, and defaults to 4096, or 4 gigabytes, the maximum amount of memory a 32-bit application can address. The amount of memory currently used for frame buffers is also shown. Note that FFRend is Large Address Aware, meaning it can access up to 4GB of memory on 64-bit operating systems, and up to 3GB on 32-bit operating systems provided boot.ini specifies the /3GB switch.
FFRend supports plugin authoring, which means you can export a FFRend project as a Freeframe plugin. The exported plugin is called a metaplugin, because it uses other plugins as components. A metaplugin can be used in any Freeframe-compatible host application, and behaves as if you were running the equivalent project in FFRend.
A metaplugin preserves all project attributes, including parameter automations and signal routing. The only significant exception is MIDI assignments; these are ignored, to avoid interfering with the host's MIDI implementation.
A metaplugin can expose parameters to the host; such parameters are called metaparameters. A metaparameter can directly control a parameter in a component plugin, or it can control other targets, such as a modulator property, or a plugin's bypass switch.
A metaplugin normally contains links to its component plugins, but it's also possible to embed the components within the metaplugin's DLL. Embedding makes it easier to distribute the metaplugin, by avoiding dependence on external files. Since embedding could potentially encourage piracy, only copyleft plugins can be embedded.
It's possible to import a metaplugin back into FFRend as a project. This allows you to edit and re-export a metaplugin, even if you don't have the project file from which the metaplugin was originally created.
Metaplugins can be nested, i.e. a metaplugin can use other metaplugins. The depth of nesting is unlimited.
Exporting metaplugins
To export the current project as a metaplugin, choose File/Metaplugin/Export. Select a destination folder and filename, and press OK. The Metaplugin Properties dialog is displayed. Customize the properties as needed, and then press OK to export the metaplugin. The Metaplugin Properties dialog can also be shown via File/Metaplugin/Properties. The properties are described below.
Note that FFRend automatically decides which video modes the metaplugin supports, as follows: the metaplugin will support a given video mode only if that mode is supported by ALL of the metaplugin's component plugins.
Importing metaplugins
It's possible to import a metaplugin back into FFRend as a project. This allows you to edit and re-export a metaplugin, even if you don't have the project file from which it was originally created. To import a metaplugin, use File/Metaplugin/Import. Select a filename, and press OK.
Note that if you only want to know which plugins a metaplugin uses, it's not necessary to import the metaplugin; it's easier to use the file browser. Find the metaplugin in the file browser's Plugins pane, right-click the metaplugin's name, and select Properties. The properties dialog lists the component plugins, and tells you whether they're linked or embedded.
Metaparameters
Like any other Freeframe plugin, a metaplugin can expose parameters to the host application; such parameters are called metaparameters. A metaparameter can directly control a parameter in a component plugin, or it can control other target types, such as a modulator property, a plugin's bypass switch, or a global property (e.g. Master Speed). Metaparameters can also be grouped so that a single metaparameter controls multiple targets.
Metaparameters allow you to design your metaplugin's interface. Part of creating a metaplugin is deciding which things to expose. Since hosts often severely limit the number of parameters a Freeframe plugin can have, it's a good idea to order your metaparameters, so that the most essential ones come first. FFRend allows a Freeframe plugin to have unlimited parameters, so if you're only going to use the metaplugin in FFRend, you can expose as many metaparameters as you like, though you still may find it helpful to be selective.
Creating a metaparameter
To create a metaparameter, first show the Metaparams control bar (View/Metaparams or Shift+E), otherwise you won't be able to see what you're doing. Select the plugin, by right-clicking on its tab, and now in the main view (beneath the plugin tabs, where the plugin automations are), right-click on the NAME of the parameter. You'll see the following context menu:
Select Metaparam, and you'll see a popup menu like this:
To expose the parameter itself, select Parameter. You can select one of its modulation properties instead, or to expose the plugin's bypass switch, select Plugin Bypass. The metaparameter magically appears as a row in the Metaparams control bar, with the slider and edit box already set to the target's current value. If you move the slider, or type a new value in the edit box, you'll see the target property change in sync.
Name and range
The metaparameter's name is generated automatically, but if you don't like the name, right-click it and select Properties, to show the Metaparameter Properties dialog. Now you can enter a custom name. You can also use this dialog to map the Freeframe parameter range [0..1] to whatever range you want. This is especially useful when the target is a modulation frequency. The range can also be inverted, e.g. to turn a "bypass" control into an "enable" control, use a range of [1..0] instead of [0..1].
Alternate method
Metaparameters can also be created via the Metaparameter Properties dialog, though the method described above is more convenient. This alternate method is the ONLY way to create a metaparameter for Master Speed. Right-click in the Metaparams control bar and select Insert. Now right-click the Metaparameter row you just created, and select Properties. In the properties dialog, go to the Plugin combo box, select Misc Properties, and you'll find Master Speed. You can use the combo boxes to select any target in FFRend. To control multiple targets, use metaparameter groups.
Reordering
The order of the rows in the Metaparms control bar determines the order in which the metaparameters will appear in the host. The order can be changed by dragging rows. To drag a row, position the cursor over the metaparameter name, press and hold down the left mouse button, drag the row to the desired location, and release the left mouse button.
Metaparameters can be grouped, so that one metaparameter controls multiple targets. This allows you to create metaplugins in which a single host parameter has multiple effects. Each group consists of a master and one or more slaves. When a master is updated (manually or via MIDI), its slaves follow it. Only masters are exposed to the host, i.e. when the metaplugin is loaded in a host application, any slave metaparameters are hidden.
Group members can control targets in different plugins, or different types of targets, e.g. a mix of parameters and modulation properties. Group members can also have different ranges. By inverting one of the ranges, it's possible to create a metaparameter whose targets move in opposite directions, as in a crossfader.
Metaparameter groups have another use unrelated to metaplugins: they allow you to assign a single MIDI controller to multiple targets. The MIDI Setup dialog limits you to one target per controller, but metaparameter groups provide a way around this restriction. To assign a single MIDI controller to multiple targets, do the following:
To create a new group, right-click the metaparameter that should be the master, and select Group from the context menu. The Metaparam Group dialog is displayed. The dialog lists the names of every metaparameter that could potentially be a slave of this group. Each name has a checkbox next to it. Use the checkboxes to select which metaparameters should belong to this group, and then press OK to save your changes. Metaparameters that already belong to a different group aren't shown, because metaparameter groups can't be nested.
To edit an existing group, right-click any member of the group, and select Group from the context menu. Again, the Metaparam Group dialog is displayed. Check or uncheck group members as desired, and then press OK to save your changes.
To destroy an existing group, right-click any member of the group, and select Ungroup from the context menu.
A metaplugin won't function unless all of its component plugins are available. There are two possible scenarios: the metaplugin can contain links to its components, or the plugins can be embedded within the metaplugin DLL. This topic deals with the first scenario, a linked metaplugin.
Since a link is an absolute path to a component DLL, links can break, e.g. if you move your plugins around, or rename folders. This is very likely to happen if you distribute a linked metaplugin, because the recipients probably won't have organized their hard drives in the same way as you.
When a linked metaplugin is loaded, it checks for broken links. If components aren't where they're supposed to be, the metaplugin searches for them, using a specific strategy. A linked metaplugin looks for its component plugins in the following places, in order:
Option #1 is the most efficient. Option #2 is useful with hosts that require all Freeframe plugins to reside in a specific folder. Regarding option #3, note that Application Data\FFRend\Plugins is also used for unpacking embedded plugins. The environment variable is discussed below.
Error handling
If one or more components aren't found in any of these places, the metaplugin disables itself. A disabled metaplugin has no effect on its input, and doesn't expose any parameters to the host. The metaplugin also writes an error message to a log file indicating which plugins are missing. The log file (Application Data\FFRend\MetaFFRend.log) is a text file, and can be viewed with Notepad or any text editor.
Broken links can be repaired by importing the metaplugin as a project. The import displays the missing files dialog, which allows you to search your hard drive for the missing plugins. If the plugins are found, you can save the repaired links by re-exporting the metaplugin.
Environment variable
The advantage of the METAFFREND_PATH environment variable is that it allows you to direct the metaplugin to any folder(s) you like. So for example if you keep your plugins in a folder hierarchy separated by author, you can leave them right where they are, instead of copying them to App Data. Multiple paths MUST be separated by semicolons.
If you've never set an environment variable, consult your Windows documentation, but generally the following should work: On the desktop, right-click My Computer, select Properties, select the Advanced tab, click Environment Variables, and in User Variables, select New. For Variable Name, enter METAFFREND_PATH, and for Variable Value, enter the search path(s), separated by semicolons if there are more than one. Don't use quotes, and be careful to avoid leading or trailing spaces. Press OK a few times and you're done. You can use other variables as examples, but don't change them or stuff will break.
By default, a metaplugin contains links to its component plugins, but it's also possible to embed the components within the metaplugin DLL. To enable embedding, check the "Embed Plugins" checkbox in the Metaplugin Properties dialog.
The advantage of embedding is that the metaplugin doesn't depend on any external files. This is especially useful if the metaplugin is being distributed to other users, because it avoids the whole problem of broken links. The user doesn't have to worry about having all the necessary component plugins in the correct locations on their hard drive; they just load the metaplugin into their host application, and it works.
The disadvantage of embedding is that it can significantly increase the size of the metaplugin DLL. On the other hand, the plugins are stored in a compressed format, which helps keep the size down.
Embedding is only allowed if ALL of the metaplugin's components are copyleft. A plugin is considered copyleft if the string "copyleft" (case-insensitive) appears in its Author/License field. The only exception to this rule is for Pete Warden's plugins. Embedding is restricted to prevent inadvertent distribution of commercial plugins. Note that this restriction also applies to metaplugins used as components; see nesting metaplugins.
How it works
When you load an embedded metaplugin into a host for the first time, the metaplugin unpacks its component plugins into a special folder in your profile: Application Data\FFRend\Plugins. If a given component is already present in this folder, it isn't unpacked. Since components aren't deleted, a metaplugin only needs to unpack itself once; the next time you run it, all of its components will already be present. This means the slight delay associated with unpacking only occurs the first time you use the metaplugin.
A metaplugin may not even need to unpack itself the first time you use it, e.g. if you've previously used a different metaplugin that shares the same components. Note that an unpacked component plugin is an exact binary copy of the original; even the file times are preserved.
A metaplugin can use other metaplugins as components. This is possible because from the host's point of view, a metaplugin is simply a Freeframe plugin, like any other. No special procedure is required; nesting occurs naturally when you include one or more metaplugins in a project, and then export that project as a metaplugin.
A metaplugin can use a combination of metaplugins and ordinary plugins, e.g. you could make a metaplugin that uses a mixer plugin to automatically crossfade between two metaplugins.
There's no limit on how deeply metaplugins can be nested. Each level of nesting results in some additional overhead, but the amount is insignificant compared to the overhead of the ordinary plugins that are actually doing the work.
Nesting lends itself to an object-oriented approach, in which simpler metaplugins are used as building blocks in higher-level metaplugins. This encourages iterative composition, and distributed creation. For example, if I make a metaplugin that does something you like, and send it to you, you can add value to it, by using it inside one of your own metaplugins.
Nesting can also be used to create modulations more complex than FFRend's built-in oscillator waveforms. For example, suppose a metaplugin exposes a parameter's modulation frequency as a metaparameter. If the metaplugin is nested within another metaplugin, the top-level metaplugin can modulate the frequency. The same technique applies to pulse width.
Nested metaplugins can be embedded, but only if all the plugins at each level are copyleft, i.e. have the string "copyleft" in their Author/License information (see exporting metaplugins). For example, if I send you a copyleft embedded metaplugin, you can embed it inside one of your metaplugins; if your metaplugin is also copyleft, it can be embedded by someone else, and so forth. When the top-level metaplugin is loaded into a host, it unpacks itself recursively.
FFRend's output can be displayed full-screen, so that the output window fills the entire display, and all other windows are hidden. The other main advantage of full-screen is that it uses DirectDraw Exclusive to eliminate tearing.
To enable or disable full-screen mode, use Window/Full Screen or Ctrl+F11.
FFRend supports a dual-monitor setup, in which its main window and output are displayed on two different monitors. In the usual case, the main window is on the primary monitor (the built-in display on laptops), and the output is on the secondary monitor, but the reverse also works.
To make FFRend use a secondary monitor, you must first extend your Windows desktop onto the secondary monitor. This is typically done using Control Panel/Display/Settings, or in some cases via software that came with your graphics card. Once you've extended the desktop, you can drag FFRend's output window onto the secondary monitor. Now when you enable full screen mode, the output window fills the secondary monitor.
Tearing is a distracting visual artifact. It typically looks like horizontal lines running up and down the image. Tearing occurs if the display is refreshed while the CPU is in the middle of writing a new frame to the graphics hardware. At that moment, both the old and new frames are partially visible, and if they differ (as is likely), the eye perceives a discontinuity (a tear) in the image.
Tearing can be only prevented by using full screen mode; this allows DirectDraw to synchronize access to the graphics hardware. In normal windowed mode, tearing is unavoidable.
FFRend attempts to maintain a constant frame rate, but if the CPU is overloaded, the frame rate will drop, sometimes drastically. CPU overload typically results from a large frame size, a long plugin chain, or especially CPU-intensive plugins. It isn't necessarily a concern when you're recording a finished project. It's more likely to be a problem when the perceived frame rate matters, e.g. during development, or during a live show.
The simplest way to improve performance is by reducing the frame size. You may find it convenient to develop your projects at a low resolution, and then increase the resolution for the final recording, but be aware that some plugins won't behave exactly the same way at different resolutions. If you have a multi-core CPU, you may also be able to improve throughput by load balancing.
The Monitor, Graph, History and Queues views all potentially reduce performance. The monitor quality setting can also affect performance, though only if the monitor bar is visible. Reducing the view frequency may increase performance slightly, at the cost of making the user interface choppier.
If you're creating complex effects at high resolution, it may not be possible to stay in real time, except by using a more powerful computer. FFRend is compute-bound, i.e. its performance is limited primarily by CPU power, rather than graphics power, memory size, or disk speed.
Given sufficient cores, FFRend runs each plugin on its own core, but this only maximizes throughput for symmetrical loads, i.e. the rare ideal case where each plugin requires the same amount of CPU time to render a frame. In practice it's common for some of a project's plugins to require significantly more CPU time than others. This situation is governed by Amdahl's law, which basically states that in a parallel system, throughput is limited by the slowest sequential task. FFRend provides a workaround, called load balancing, which can greatly improve the throughput of asymmetrical loads in some (but not all) cases.
The main limitation of load balancing is that it only works for stateless filters, i.e. plugins that don't store any type of history. Plugins that won't work include source plugins, time blurs, feedbacks, and plugins with internal oscillators. The reason they don't work can be illustrated as follows. Suppose we have a crude time blur that simply outputs the average of the current frame and the previous frame. Allocating two threads to a plugin results in two instances of it, one processing even-numbered frames, and the other processing odd-numbered frames. Since each instance has its own previous frame, we now have two different versions of the average, and the output alternates rapidly between them. This appears as strobing and clearly isn't what we want. The good news is that many useful but CPU-intensive plugins are stateless, including most blurs and keys. Note that if a plugin is only stateful because of its internal oscillators, it may be possible to make it stateless by disabling the oscillators.
To show the Load Balance control bar, use View/Load Balance or Shift+L. The bar allows you to specify the number of threads allocated to each plugin. Plugins are initially allocated one thread apiece. The bar also shows the current CPU usage of each plugin thread, both as a percentage and in milliseconds. The percentage indicates how much of one core the corresponding thread is using. If it's 100%, the thread is saturating a core and may be limiting throughput.
To change the number of threads allocated to a plugin, edit its thread count and press Tab, or left-click the edit control's up/down buttons. Changes are applied immediately, but the load balance statistics can take up to a second to update. Load balance settings are project-specific and are therefore saved in the project file.
Successful load balancing often involves trial and error. The following example may be helpful. Suppose a project has three plugins: A, B, and C, connected in series. B takes twice as long as A, and C takes twice as long as B. Assume the frame size is big enough so that we're not achieving the desired frame rate, and also assume we have eight cores to play with. The load balance dialog shows that A is using a negligible amount of CPU, B is using about 50%, and C is using 100%. C appears to be the bottleneck, so we allocate two threads to C. B now increases to 100%, and C's two threads each use about 100%, but the frame rate is still unsatisfactory, so we add another thread to C. C now has three threads, but they each use only 65%, and the frame rate doesn't improve. Surprise! This means C is starved for input. Since B is now the limiting factor, we add a second thread to B. B's two threads use 75%, and C's three threads increase to 100%. We're back to C being the bottleneck, so we add one more thread to C. B now has two threads at 100%, while C has four threads at 100%, and that's the best we can do with eight cores.
If adding extra threads to a plugin fails to increase throughput, it's because either that plugin is starved for input, or the CPU is fully loaded. In the former case the solution is to identify and address the bottleneck; in the second case, there's no solution, other than a new CPU. Both cases exhibit the same symptom: more threads doing less work. The cases can be distinguished by examining the task manager. If you're not achieving your requested frame rate, but the CPU isn't fully loaded according to the task manager, one or more plugins must be starved for input. It's also possible to determine this from the percentages in the Load Balance dialog. The sum of all the percentages can't exceed 100% times the number of cores. If you have four cores, but the percentages only add up to 300%, a core must be idle (assuming no other CPU-intensive applications are running), and tweaking the balance could yield further gains. The ultimate proof of success is improved frame rate.
Note that running all cores at 100% can potentially make the GUI sluggish, and may worsen MIDI latency. This is an important factor if you're using FFRend for live performances, but it might not matter if you're only recording movies.
FFRend solves the frame-dropping problem which occurs in some VJ softwares. To understand why frame-dropping is a problem, you need a little background about Microsoft DirectShow.
DirectShow is a component of Windows that deals with playing video and audio. Windows VJ softwares often use DirectShow to display video. DirectShow is a "streaming" technology, which means it tries to keep the video in real time at any cost. If the video falls behind (e.g. due to CPU-intensive effects, high resolution, or limited disk bandwidth), DirectShow drops (i.e. omits) as many frames as necessary to catch up. The advantage of DirectShow is that the application doesn't have to worry about keeping its video and audio synchronized.
The problem is that DirectShow-based VJ softwares typically record the same output that's being displayed. This means that if dropped frames occur in the displayed output, the recording will also contain dropped frames. The result is that in certain situations--e.g. if you're using many CPU-intensive effects, or a high output resolution--it can be impossible to make a clean recording. This is the very frustrating problem that FFRend was designed to solve.
Since FFRend doesn't use DirectShow, it isn't restricted to a fixed frame rate. Instead, it allows the frame rate to vary as needed. If the CPU is overloaded, the frame rate slows down, but frames are NEVER dropped, either in the displayed output or in the recording.
FFRend can automatically open a list of projects, also known as a playlist. This is useful if you're VJing and need a break. It also makes it easier to use FFRend in an installation (see below). The Playlist dialog allows you to specify the list of projects, the interval between project changes, whether the list should be played in sequential or random order, and whether it should loop. Use Edit/Playlist or Shift+A to show the Playlist dialog.
The Playlist dialog has its own menus. To add projects to the playlist, use Edit/Add or Edit/Insert. To delete projects from the playlist, use Edit/Delete. You can also drag projects onto the Playlist dialog from the Projects pane of the Files Bar, or from Windows Explorer. To save the playlist use File/Save or File/Save As. To start a new playlist, use File/New. To open an existing playlist, use File/Open.
To play the current playlist, use Auto/Play, or press the dialog's Play button. While playing, the current project indicator (in the playlist's leftmost column) changes from a black square to a green arrow. To stop playing the playlist, press the Play button again. To loop the playlist, use Auto/Loop, or press the Loop button. To randomize the order of the playlist, use Auto/Shuffle, or press the Shuffle button. To specify the interval between project changes in seconds, use the edit box to the right of the buttons.
A playlist file contains links (paths) to project files, and these links can break if project files are moved or deleted. If this occurs, FFRend displays the missing files dialog when the playlist is opened.
When creating an installation, it may be desirable to have FFRend start up playing a playlist. This is accomplished by passing FFRend the playlist via the command line. It may also be helpful to specify the /fullscreen command-line option, which causes FFRend to start up full-screen on whichever monitor contains the output window. Here's an example command line:
ffrend myplaylist.ffl /fullscreen
The parameter view and some of the control bar views have resizable columns. The columns are resized via the column header, just as in a standard list control. To resize a column, move the cursor to the column header and position it over the divider to the right of the column you want to resize. The cursor changes to a vertical bar with two arrows. Press and hold down the left mouse button, and drag the divider horizontally until the column has the desired width.
It's possible to hide a column by reducing its width to zero. A column hidden in this manner can be restored as follows: move the cursor to the column header and position it slightly to the right of the divider where the hidden column used to be. The cursor changes to a double vertical bar with two arrows. Press and hold down the left mouse button, and drag the cursor to the right to restore the hidden column.
To reset a column to its default width, double-click the divider to the right of the column. To reset all columns to their default widths, first ensure the view has input focus, e.g. by left-clicking anywhere within its column header, and then while holding down the Ctrl key, press the + key on the numeric keypad. If you're using a laptop, it may not have a dedicated numeric keypad, in which case you may need to also hold down a function key that enables numeric keypad mode.
Metaparameter groups
Metaplugin links
Embedding plugins
Nesting metaplugins
Loose Ends
Full screen
Dual-monitor
Tearing
Performance
Load balance
Frame-dropping
Playlist
Column resizing
Shortcuts
| Shift+A | Edit Playlist | Edit the playlist |
| Ctrl+C | Copy | Copy the selection and put it on the Clipboard |
| Ctrl+E | Export | Export current frame as a bitmap |
| Shift+E | Toggle Metaparams | Show or hide the metaparameters bar |
| Shift+F | Toggle Files | Show or hide the files bar |
| Shift+G | Toggle Graph | Show or hide the graph bar |
| Shift+H | Toggle History | Show or hide the history bar |
| Shift+I | Toggle MIDI | Show or hide the MIDI bar |
| Ctrl+L | Load | Load the selected plugin |
| Shift+L | Toggle Load Balance | Show or hide the load balance bar |
| Shift+M | Toggle Master | Show or hide the master bar |
| Ctrl+N | New | Create a new document |
| Shift+N | Toggle Monitor | Show or hide the monitor bar |
| Ctrl+O | Open | Open an existing document |
| Shift+O | Edit Options | Edit the options |
| Ctrl+P | Print the active document | |
| Shift+P | Toggle Patch | Show or hide the patch bar |
| Shift+Q | Toggle Queues | Show or hide the queues bar |
| Ctrl+R | Record | Record the output to an AVI file |
| Shift+R | Toggle Record Status | Show or hide the record status dialog |
| Ctrl+S | Save | Save the active document |
| Shift+U | Toggle Output | Show or hide the output window |
| Ctrl+V | Paste | Insert Clipboard contents |
| Alt+Backspace | Undo | Undo the last action |
| Delete | Delete | Delete the selected plugin |
| Shift+Delete | Cut | Cut the selection and put it on the Clipboard |
| F1 | Help | List Help topics |
| Ctrl+F11 | Full Screen | Display the output full screen |
| F4 | Job Control | Show or hide job control dialog |
| F5 | Refresh | Refresh the views |
| F6 | Next Pane | Switch to the next window pane |
| Shift+F6 | Previous Pane | Switch back to the previous window pane |
| F8 | Monitor Plugin | Monitor the selected plugin |
| F9 | Bypass | Bypass the selected plugin |
| Insert | Insert | Insert a plugin |
| Ctrl+Insert | Copy | Copy the selection and put it on the Clipboard |
| Alt+Insert | Insert Empty | Insert an empty plugin slot |
| Shift+Insert | Paste | Insert Clipboard contents |
| Space | Pause | Pause the output |
| Shift+Space | Step | Single-step the output |
| Ctrl+X | Cut | Cut the selection and put it on the Clipboard |
| Ctrl+Y | Redo | Redo the previously undone action |
| Ctrl+Z | Undo | Undo the last action |