PixelToy Reference Version 3.0
LairWare Software

 File Menu

This PixelToy Reference document is divided up into sections representing each menu bar heading. These sections will help you understand the various PixelToy control windows as well. If you haven't yet read the PixelToy Manual, it is recommended that you understand the concepts explained there before consulting this reference.  
File Menu
Open Sets... | Open Picture... | Reload last Picture | Save PNG... | Save Current Sets As... | Create Movie... | Clear Screen | Pause | Close Window  
Open Sets...
Open a Sets file. When launched normally, PixelToy automatically uses the "PixelToy Sets" file stored in the same folder as your application preferences. With this command, you can open a different group of Sets to use. You can achieve the same effect by opening a particular Sets file in the Finder, or by drag-and-dropping it onto PixelToy's icon.
Open Picture...
Open a picture to be distorted and drawn upon. All common image formats are supported (JPEG, PNG, GIF, etc.). Images are treated as grayscale when opened, and color information is ignored because PixelToy generates its own color. Normally, PixelToy will resize the window to match the image's dimensions, however you can disable this in the Preferences dialog. Note: This command loads your picture once, with the Filters acting upon the resulting image over time to remove it. If you want your picture to remain in the display, use the Images action instead.
Reload last Picture
Wow, PixelToy sure destroyed that picture quickly! Reload it again automatically with this command. PixelToy will not resize the window to fit the image; if you want it to, reopen the image with Open Picture.
Save PNG...
Save the window's current contents as a PNG image.
Save Current Sets As...
Save all sets shown in the Sets menu into a new Sets file. After doing this, any further changes to the Sets will be saved to this file. See About sets for more general information.
Create Movie...
Start saving a QuickTime Movie. First, you'll be asked if you want a Fixed Frame Rate or Real Time. A fixed frame rate lets you specify exactly how fast you would like the movie to play back after you have created it, regardless of how quickly or slowly the movie is created. You specify this Frames Per Second number in the QuickTime window you get after selecting a file name for your movie. If you choose Real Time, the Frames Per Second value in the QuickTime window is ignored, and instead the resulting movie will play back at precisely the same speed at which it was recorded, allowing you to later synchronize it with audio, for example. In the QuickTime window you'll also be asked what compression method to use -- if your movie is intended to play back smoothly, you'll want either the Video or Cinepak compressor. If you're generating footage that will be used in a video editor such as iMovie or Adobe After Effects, you'll want Photo - JPEG with quality nearly maximum. If you're recording in Real Time, the Video compressor (maximum quality, no keyframes) is a good choice as it compresses very quickly. After starting to create a movie, you can hold down command-period or select this same menu command (which will be called "Stop Movie") to end movie creation. Tips: Use the Preferences window to set the size of PixelToy's window numerically. You can do anything in PixelToy while generating a movie except resize the PixelToy window.

When you are finished creating the movie, select this menu command again, which will be instead named "Stop Movie". Movies created in this manner are ready for use in many video editor programs. To use QuickTime movies such as this within iMovie, you'll need QuickTime 7 Pro (the $30 full featured edition). Open your PixelToy QuickTime movie in "QuickTime Player 7" application (found Applications/Utilities/) and select "Export..." from the File menu. On the next window change the "Export:" pop-up menu to "Movie to DV Stream". It may take a while to save, and you'll end up with a rather large DV file that you can import into iMovie and treat like just any other video clip.
Clear Screen
Wipes the PixelToy window clean.
Halts animation. Select this command again to start the animation again. This command is particularly handy when creating a movie; set all of your options, pause, clear screen, then begin creating the movie. Nothing will be written to the movie until you un-pause the animation.
Close Window
As you might expect, except that if you close the main PixelToy window, the program will completely quit.
Options Menu & Window

Autopilot | Pixel Doubling | High-Quality | Full Screen | Dither Updates | Configure Autopilot | Preferences | Apply Filters Last | Image Emboss | Sound Visual Options | Text Options | Particle Options | Image Options | Misc Options

The Options control window is identical to the pull-down menu; "checked" items are shown brighter than normal items. The first section of the Options menu and control window consists of global settings which persist even when loading sets.
With the Autopilot enabled, PixelToy will periodically change actions, action options, filters, mirroring, and/or color palettes. See Configure Autopilot for details.
Pixel Doubling
Speeds up animation by lowering the image quality. Can't be on at the same time as High-Quality mode.
Increases the image quality, which slows down animation quite a bit. Generally only useful with small windows sizes or when creating Fixed Frame Rate movies. Can't be on at the same time as Pixel Doubling.
Full Screen
Toggles between Full Screen and windowed mode. While in Full Screen mode, you can make the menu bar appear by clicking up where it should be; it will become visible. The first time you activate Full Screen mode, you will be asked if you would like your main display switched to low resolution whenever you enter Full Screen mode in the future; you may later change your mind in the Preferences window. If you quit while in Full Screen mode, PixelToy will remember to reactivate it automatically the next time it is launched. On multiple monitor systems, first drag the main PixelToy window entirely onto the monitor you wish to use before invoking this command. Going to full screen mode hides the other windows -- if you would like them back while still in full screen mode, use the Show All command in the Windows menu.
Dither Updates
Only has an effect when the display is configured to display only Thousands of colors, this option will mix colors when drawing to avoid the bands of solid color that tend to appear in Thousands of colors otherwise.
Configure Autopilot
This window allows you to fine-tune PixelToy's AutoPilot command. You may specify the number of seconds between changes, and select what the AutoPilot is allowed to randomly modify:

Turn these actions on and off: Any actions highlighted here may be turned entirely on or off by the AutoPilot. The AutoPilot will not allow more than 3 actions to be on at the same time.
Change options for these actions: With this selected, the AutoPilot may change options (such as size) for any actions which are both highlighted here and and currently being displayed in PixelToy's main window.
Allow sound reaction: Allows the AutoPilot to turn on the Sound Visuals action or activate sound-reaction options on other actions.
Always react to sound: Forces the AutoPilot to use sound-reaction options on all actions.
Filters and Mirrors: Simply allows filters and mirrors to be turned on and off. The AutoPilot will only use one filter at a time.
Use random color palette: Lets the AutoPilot do the equivalent of selecting Random from the Colors window.
Use saved color palette: Allows the random selection of any named color palette listed in the Colors window.

This tabbed dialog lets you control many global settings of PixelToy.

Change Display for Full Screen: When selected, the two pop-up menus allow you to select any resolution and color depth supported by your video system. Note that resolutions not supported by your monitor may appear in this list! For those with multiple monitor systems, the resolutions shown are for the monitor on which the PixelToy animation window is currently displayed (i.e. the monitor which will be used for full screen mode).
Speed Limit will restrain the animation speed to the number of frames-per-second that you type here.
Window Size allows you to set exact dimensions for the PixelToy window, useful when creating movies.
Frames for palette transition defines how many frames of animation are used to change color palettes. Has no effect when displaying less than Thousands of colors.
Don't Let Images Resize Window keeps the Open Picture command from resizing the PixelToy window to the size of the image being opened.
Don't Show Splash-Screen keeps the About PixelToy window from appearing when you start PixelToy.
Use First Set of Opened Sets enables PixelToy to automatically use the first set in a Sets file when the file is double-clicked or drag-and-dropped on PixelToy.
Show Set Comments allows a set to display its comments when it is used.
Allow Rough Random Colors permits the Random Palette command to create more rough-edged palettes.
Keep Mouse Hidden hides the mouse cursor when it is over the PixelToy window.
Note Missing Fonts allows PixelToy to notify you when you load a set that uses fonts not installed on your computer.
Show Frames Per Second activates a number display on the title bar of the PixelToy window, displaying how many frames of animation PixelToy has been able to generate in the last second.

The Audio Device pop-up menu allows you to select an audio input device for PixelToy to react to. If you don't see "Built-in" choices available, you may need a USB microphone in order for PixelToy to react to audio. An audio device may potentially have several different Audio Sources to choose from, though most devices seem to just have one.
Play Audio Input through Output allows you to hear this audio input from your Mac's sound system. Note that this feature is not available with most audio devices.
Auto Device Hardware Gain settings, if supported by your device, may automatically improve PixelToy's reaction to loud or quiet audio sources.
Hardware Gain allows you to manually adjust the volume of your audio input source to a suitable level. Once again, setting hardware gain may not be supported by your device. If you adjust this value and use Auto device Hardware Gain, there's no telling what your device will do.
Software Gain does not depend on device capabilities, and can always be used to amplify PixelToy's reaction without affecting the audio level when played through output.

The second section of the Options menu and control window consists of local settings that are stored in sets.
Apply Filters Last
Apply Filters Last makes PixelToy apply the Filters after the Actions, instead of the normal behavior of applying the Filters before the Actions. This is particularly useful when using the Kaleidoscope filter.
Image Emboss
This option applies a graphic filter that makes the normal display appear as protrusions and indentations in a surface. Embossing usually looks best with a continuously shaded color palette such as Greyscale; if you generate a random color palette while Image Emboss is enabled, the created palette will be continuously shaded.
Sound Visual Options
Up to 16 different sound visual objects can be created and edited here. Four types of objects may be used (see below), along with the ability to size, move, flip, rotate, and otherwise customize your display.

List order: Sound Visual objects are drawn from the top of the list down; therefore, if you have overlapping objects, the lower item in the list will appear on top of a higher item. You can use the To Back and To Front buttons to shuffle your objects around.

Type: Four fundamental object types exist as shown below. The "Sound Wave" is the default object, resembling an oscilloscope display. The other three types all use frequency amplitudes to create a "graph" of current sound frequencies as either a bar display, brick-like blocks, or a line display.
Sound Wave
Frequency Bar
Frequency Brick
Frequency Line

Action: Stationary stays where you put it. Vertical Slide slowly bounces from the top of the display to the bottom and back again. Horizonal Slide does the same but left to right. Wandering makes the object bumble around with a mind of its own. Random Jumping objects appear at a different place constantly. Finally, Mouse make the object appear where the mouse cursor is, usually with the 'Keep Mouse Hidden' option in the Preferences window.

Solid objects are entire regions instead of mere lines. The Thickness option is ignored when an object is solid.

Rotate 90 degrees: Tip an object on its side for a vertical sound wave or horizontal bars.

Flip Horizontal and Flip Vertical does as you might imagine, though for a Sound Wave the effect is not particularly noticeable unless it is also solid.

Brightness dictates what color from the palette in which the object is drawn.

Thickness simply controls how thick the lines are drawn. This option is ignored when an object is solid.

Spacing indicates the distance between individual Frequency Bars and Bricks, and is ignored for Sound Waves and Frequency Lines.
Text Options
You can edit all aspects of text in PixelToy within this window. Create up to 16 different text objects, each with its own font, action, brightness, and size.

List order: Text is drawn from the top of the list down; therefore, if you have overlapping text objects, the lower item in the list will appear on top of a higher item. You can use the To Back and To Front buttons to shuffle your text objects around to your liking.

Actions: Stationary merely stays where you put it. Jitter causes the text to vibrate like it's fulla caffeine. Bouncing (Zero G) makes the text bounce off the four walls like a ball in Pong. Bouncing (Gravity) will make the text bounce like a ball trapped in a box, until it slows down, at which point it is given a kick to get moving again. Wandering text objects bumble around at random. Mouse simply makes the text appear where the mouse cursor is. This one is best accompanied by activating the 'Keep Mouse Hidden' option in the Preferences window. Finally, Vibrate is a bit calmer version of Jitter.

Outline: Select this item to draw an outline around this text object to improve its readability. This option can considerably slow down the animation.

Brightness: Fixed allows you to specify a brightness level with the slider control. Pulsing makes the text brightness go from 0% to 100% and back to 0% continuously. Based on Sound makes the brightness of the text depend on the sound volume of the currently selected sound input device.

Size: Text size is expressed as a percentage of the window height; values anywhere from 0% to 400% are allowed. Based on Sound makes the text size change based on the sound volume of the currently selected sound input device, with maximum volume resulting in the percentage size specified.
Particle Options
All particle controls are located on this window. You can have up to 16 different particle generators defined, listed on the left.

Name: This is for your organization only; the name isn't displayed anywhere else in PixelToy.

Particle Type: Water is the default type. Bugs bumble around, and if solid, will periodically land on bright objects. Snow falls from the top of the screen and (once again, if solid) will collect on bright surfaces. Repulsion particles avoid bright objects and each other.

Action: Stationary generators stay still. Follow Mouse aims the generator in the general direction of the mouse cursor. You may want to activate the 'Keep Mouse Hidden' option in the Preferences window along with this. Random makes the generator randomly point in different directions. React To Sound makes the Flow Rate and speed of the generator based on the sound volume of the currently selected sound input device.

Other Controls: Flow Rate adjusts the amount of particles which come out of the generator. Gravity controls the force pulling the particles to the bottom of the window. Particle Size controls the size of the individual particles; to ensure that the particles look the same with and without Pixel Doubling enabled, set the size to at least 10%. Spout Width and Spout Height control the size of the area from which the particles are emitted. Spray controls how much particles can randomly vary from the direction and speed you have defined in the preview window. Brightness determines the color in which these particles are drawn. Bounce off walls & ceiling allows you to only let the particles out through the bottom of the window. Solid particles are affected by other objects (including each other). Be careful; if your flow is high and your spout is small, solid particles will bunch up and 'clog up' the particle generator. Repulsion particles are always solid. The Blend All button replaces the settings of all of your generators except the first and last one, changing them to blended steps. It is helpful to experiment with this last button in order to fully understand it.
Image Options
Everything controlling the display of image objects is accessed in this window. You can have up to 16 image objects defined. Clicking in the preview window lets you select, move, and resize your image objects.

You can use your images in two different modes, 1-Bit or 8-Bit: 1-Bit images are 'flat' and only display two colors. When 1-Bit images are transparent, only the light color is drawn, leaving other areas untouched. You can control the 'brightness' of 1-Bit images by defining it as Fixed where you select a value with the slider control, Pulsing constantly changes from 0% to 100% back to 0% brightness, and Based on Sound will set the brightness based on the volume of the current sound input. 8-Bit images can use the entire PixelToy color palette of 256 colors, but their brightness is unchangeable. To make an 8-Bit image transparent, you must select another image file to use as a 1-Bit mask file.

When you add a new image with the Add button, PixelToy will attempt to use an image file named "Default Image" and mask file named "Default Mask" in the same folder as the PixelToy application. If you have not provided one, Mona Lisa stands in until you select an image yourself.

Action: See the description for Text objects -- all behaviors for images are the same.

Other controls: Invert reverses black and white in the image (or mask) file. Keep Proportional forces image resizing to remain at the original image's aspect ratio. This check box also affects the Autopilot's ability to randomly resize image objects. Reset Size will set the current image object's size to the actual pixel size of the selected image file. If you hold down the option key when clicking Reset Size, all image objects will have their sizes reset. On Top Of Other Actions forces this image object to be drawn after all other PixelToy actions, assuring it will not be obscured by anything (other than possibly other image objects also using this feature).

Image files you have selected are NOT stored in PixelToy or PixelToy's Sets files in any way -- if you move any image files you refer to with a PixelToy image object, PixelToy may not be able to find and draw it. Here's where PixelToy looks for images:
  1. Where it was originally when selected in PixelToy
  2. The directory of the current Sets file
  3. Pictures directory in home directory (OS X only)
  4. The directory in which the PixelToy application resides
If you transfer a Sets file to another computer, be certain to include any image files you are using as image objects!
Misc Options
Actions other than the Sound Visuals, Particle Generator, Text, and Images are customized here. Control the number, size, and other features for each action individually.

Actions Menu & Window

Bouncing Lines | Wander Balls | Insect Swarm | Raindrops | Sound Visuals | Doodle | Text | Particles | Images

Tip: Holding down the option key when clicking on a button in the Actions window will take you a dialog to let you edit that action's parameters.
Bouncing Lines
Lines that arc and bounce across the screen. You can use the Misc Options dialog to control how many lines exist, line thickness, and whether or not they change size based on sound input.
Wander Balls
Circles that wander aimlessly around the screen. You can use the Misc Options dialog to control how many dots exist, ball size, and whether or not they change size based on sound input.
Insect Swarm
A swarm of bees tries to catch the queen bee, while the queen bee chases after a point that changes every time it catches it. You can use the Misc Options dialog to make the queen bee chase the mouse cursor, hide the queen been, define how many bees exist, control how quickly the 'drones' react to the queen, and specify whether or not they change size based on sound input.
Random circles splat all over the screen like fat raindrops. Use the Misc Options dialog to control rain rate, size and sound reaction.
Sound Visuals
Enables any defined sound visual objects to be drawn. Use the Sound Visual Options command to create and manipulate these objects.
With this option turned on, you can click and drag in the PixelToy window to draw. You can control line thickness in the Misc Options dialog.
Enables any text objects to be drawn; see the Text Options command for information on creating text objects.
Enables any particle generators to be drawn; see the Particle Options command for information on creating particle generators.
Enables any image objects to be drawn; see the Image Options command for information on creating image objects.

Filters Menu & Window
About Filters
Menu bar: Selecting these menu items toggles the filter you selected; you can have any number of filters turned on, though the more filters you have on, the slower the animation will be. You can activate a filter by itself by pressing the letter key associated with its name in the pull-down menu; all other filters are then turned off automatically. If you want to add a filter via the keyboard, hold down the shift key when typing the letter. Mirror settings can likewise be toggled by pressing the number key associated with their names in the menu.

Filter window: Active filters are shown in red. Clicking on a filter icon activates that filter by itself. To add a filter, shift click on its icon. Holding down the option key when clicking on the 'custom' filter icon brings up the Edit Custom Filter dialog window. Mirror buttons control image mirroring.

Mirroring: Vertical Mirror divides the PixelToy display into two halves, with the right half being a reflection of the left half. Horizontal Mirror unsurprisingly does the same thing for top and bottom halves. Both may be active at the same time for a nice effect. The Constrain mirror option forces all filters and actions to not act directly upon the reflections, and therefore only has an effect if a mirror is active.


(No Mirror)

Edit Custom Filter
All of the preset filters are fast because they are optimized specifically for what they do. If none of the presets do what you want, you may be able to achieve the desired effect via the Custom Filter. Every pixel that is filtered through the custom filter uses this table of numbers to determine the filter behavior. The center cell represents the pixel you are generating, all others represent neighboring pixels. A number represents the weight, or importance of a pixel. In this example, the original pixel is worth 40, the pixel directly below is worth 32, and so on. All of the pixel values are added up based on these weights, and divided based on the target value. Normally you want your total and target equal (100%), but interesting effects can be generated by setting a lower or higher target. Numbers used here are arbitrary and are only important in their values relative to one another. The percentage shown next to the total is the only absolute number used in this dialog. You can load and save custom filter settings -- the quickest way to learn how the custom filter works is to load some of the included filters and observe the resulting effect. Any changes you make to these numbers have no immediate effect until you either click the Apply button or the OK button. Note that because of its user-defined nature, the Custom Filter is not optimized and can be several times slower than the preset filters.

Colors Menu & Window
Random | Add this Palette... | Delete a Palette... | Previous | Next | Palette Animation
About Color Palettes

Clicking on a color palette in the Colors window uses that palette. Adjusting the 'Frames for palette transition' number in the Preferences dialog allows you to control the speed at which the new palette takes effect. However, if PixelToy's graphic window is on a monitor displaying 256 colors or less, palette transitions are always immediate. In addition to handling the task of palette selection, you can activate color palette animation features here as well.
Generates a new palette randomly. They can't all be gems - luckily the random palette generator is instantaneous. Activating the 'Allow Rough Random Colors' option in the Preferences dialog will make the generated palettes more rough-edged. If you have the Image Emboss option turned on, the palettes generated will be of only one hue, in a smooth gradient.
Add this Palette...
Allows you to add the current color palette to PixelToy's Colors window. After adding a color palette, you can always return to it by selecting it again. Technical Note: Color Palettes are stored in your Preferences folder in a file named PixelToy Palettes. You can delete this file while PixelToy is not running in order to reset the list of color palettes to the original set included with PixelToy.
Delete a Palette...
Here you can remove that truly awful color palette you created earlier. You can delete any palette stored in PixelToy, including the ones PixelToy came with. However, you can't delete the 'Grey' palette.
Activate the previous color palette listed in the Colors menu.
Activate the next color palette listed in the Colors menu.
Palette Animation
These 5 menu commands, along with their corresponding 5 icons at the top of the Colors window, allow you to activate an array of color animation effects which react to sound. These effects require at least Thousands of colors, and are best explained by trying them out yourself. Audio Black to Color adjusts the colors anywhere from black for silence up to full normal color for top volume. Audio Color to White scales the colors from normal for silence up to pure white for top volume. Audio Color Invert adjusts the colors from normal for silence up to complete color inversion for top volume - for example, red becomes cyan, blue becomes yellow, and so on. Audio Color Rotate changes all color palette positions based on the volume of the audio, which is truly wicked.
Sets Menu & Window
Add this set | Delete a set | Rename a set | Edit set comments | Zero Settings | Timed Set Cycle | Previous | Next
About Sets

Clicking on a set in the Sets window will load it. Holding down the option key when clicking on a set allows you to rename it.
Add this set...
This command allows you to take a 'snapshot' of all of the current settings and save them under a single name. You can then later select this name from the Sets menu to restore these settings all at once.
Delete a set...
Allows you to delete a set from the Sets menu. If you want to remove them all, just delete the current Sets file while PixelToy isn't running.
Rename a set...
Since Sets are always listed in alphabetic order, this is a handy way to arrange your sets in the order you want them.
Edit set comments...
Edit the comment for an existing set. If the Show Set Comments option in Preferences is on, the comment is displayed when the set is loaded.
Zero Settings
This command turns off all filters and all actions, selects a grey color palette and resets default set options. Therefore, since the keyboard equivalent of this is Command-Z, great woe shall betide those who assume that PixelToy has Undo capability.
Timed Set Cycle...
After selecting this option, you can specify how many seconds you wish to elapse between set changes. This effectively selects the Next set command for you every X seconds. Select this command again to stop set cycling.
Activate the previous set defined in the Sets menu.
Activate the next set defined in the Sets menu.
Show/Hide All | Move & Size As Group | Default Positions | Show/Hide other
Show/Hide All
Use this command to show or hide all of the control windows at once. If any control windows are showing, this command will hide them. Otherwise, it will show all control windows.
Move & Size As Group
With this option active, moving any control window or the main PixelToy window will move all windows. Additionally, resizing the main PixelToy window will appropriately move any control windows to the right or below the PixelToy window. You can hold down the option key on your keyboard when moving a window or resizing the main PixelToy display to have the opposite effect of what is defined here in the Windows menu.
Default Positions
This command moves your PixelToy window (at its current resolution) to the center of your display and arrays the control windows all around it.
Show/Hide other
All other commands in this menu are used to individually show or hide specific control windows.

Return to PixelToy Manual