Quartz Composer Web Kit Plug-In Programming Guide

Quartz Composer Web Kit Plug-in Programming Guide

2006-08-07 Simultaneously published in the United Apple Computer, Inc. States and Canada. © 2006 Apple Computer, Inc. Even though Apple has reviewed this document, All rights reserved. APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS No part of this publication may be DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A reproduced, stored in a retrieval system, or PARTICULAR PURPOSE. AS A RESULT, THIS transmitted, in any form or by any means, DOCUMENT IS PROVIDED “AS IS,” AND mechanical, electronic, photocopying, YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND recording, or otherwise, without prior ACCURACY. written permission of Apple Computer, Inc., IN NO EVENT WILL APPLE BE LIABLE FOR with the following exceptions: Any person DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES is hereby authorized to store documentation RESULTING FROM ANY DEFECT OR on a single computer for personal use only INACCURACY IN THIS DOCUMENT, even if and to print copies of documentation for advised of the possibility of such damages. personal use provided that the THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN documentation contains Apple’s copyright LIEU OF ALL OTHERS, ORAL OR WRITTEN, notice. EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any The Apple logo is a trademark of Apple modification, extension, or addition to this Computer, Inc. warranty. Some states do not allow the exclusion or Use of the “keyboard” Apple logo limitation of implied warranties or liability for (Option-Shift-K) for commercial purposes incidental or consequential damages, so the above limitation or exclusion may not apply to without the prior written consent of Apple you. This warranty gives you specific legal may constitute trademark infringement and rights, and you may also have other rights which vary from state to state. unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010

Apple, the Apple logo, Logic, Mac, Mac OS, Macintosh, Quartz, and QuickTime are trademarks of Apple Computer, Inc., registered in the United States and other countries. Safari is a trademark of Apple Computer, Inc. Java and all Java-based trademarks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Contents

Introduction Introduction to Quartz Composer Web Kit Plug-in Programming Guide 7

Who Should Read This Document? 7 Organization of This Document 7 See Also 8

Chapter 1 Using the Quartz Composer Web Kit Plug-in 9

Quartz Composer Web Kit Plug-in Availability 9 Including a Composition in an HTML File 10 Manipulating a Composition using JavaScript 10

Chapter 2 Quartz Composer Web Kit Plug-in Reference 13

Quartz Composer Web Kit Plug-in HTML Attributes 13 Quartz Composer Web Kit Plug-in JavaScript API 14 Methods by Task 14 Methods 15

Appendix A Allowed Patches and Filters 21

Patches and Filters Allowed by the Quartz Composer Web Kit Plug-in 21

Document Revision History 27

Chapter 1 Using the Quartz Composer Web Kit Plug-in 9

Listing 1-1 The embed tag for a composition 10 Listing 1-2 Changing a composition’s values via JavaScript 11

Introduction to Quartz Composer Web Kit Plug-in Programming Guide

Quartz Composer is a development tool for processing and rendering graphical data using an easy-to-use visual programming approach and the rich media technologies available on Mac OS X. The Quartz Composer Web Kit plug-in, available in Mac OS X v.10.4.7 and later, displays Quartz Composer compositions in webpages and Dashboard widgets.

Who Should Read This Document?

Quartz Composer Web Kit Plug-in Programming Guide is for web content and Dashboard widget creators looking to incorporate a Quartz Composer composition into a webpage or Dashboard widget. You will learn how to include a composition in an HTML file and how to manipulate it via JavaScript. You will also find a reference for the HTML attributes and JavaScript API available from the Quartz Composer Web Kit plug-in.

To learn how to create a composition using Quartz Composer, read Quartz Composer Programming Guide.

Organization of This Document

This document contains the following chapters:

■ “Using the Quartz Composer Web Kit Plug-in” (page 9) walks you through including a Quartz Composer composition in an HTML file and manipulating it via JavaScript.

■ “Quartz Composer Web Kit Plug-in Reference” (page 13) documents the HTML attributes and JavaScript API available when using the Quartz Composer Web Kit plug-in.

This document also contains a list of all of the Quartz Composer patches and Core Image filters allowed in compositions rendered by the Quartz Composer Web Kit plug-in. You can find the list in “Allowed Patches and Filters” (page 21).

See Also

To learn more about Quartz Composer and creating compositions, read Quartz Composer Programming Guide.

Safari HTML Reference, Safari CSS Reference, and Safari JavaScript Programming Topics provide information on creating content for Web Kit-based browsers like Safari.

For more on Dashboard widget creation, read Dashboard Tutorial and Dashboard Programming Topics.

Using the Quartz Composer Web Kit Plug-in

Quartz Composer, introduced with Mac OS X v.10.4, is a tool for processing and rendering graphical data. Using Quartz Composer, you combine the media technologies available on Mac OS X with an easy-to-use visual programming approach to build rich motion graphics without writing a single line of code. The resulting compositions can be used in native Mac OS X applications, QuickTime movies, and with the introduction of the Quartz Composer Web Kit plug-in, in webpages and Dashboard widgets.

In this chapter, you learn how to include a Quartz Composer composition in a webpage or Dashboard widget (“Including a Composition in an HTML File” (page 10)) and how to manipulate a composition via JavaScript (“Manipulating a Composition using JavaScript” (page 10)). Also, information on the availability of the Quartz Composer Web Kit plug-in is found in “Quartz Composer Web Kit Plug-in Availability” (page 9).

For a listing of all of the HTML attributes and the JavaScript API available when using the Quartz Composer Web Kit plug-in, read “Quartz Composer Web Kit Plug-in HTML Attributes” (page 13). To learn how to use Quartz Composer to create a composition that you can use in a webpage or Dashboard widget, read Quartz Composer Programming Guide. For a list of Quartz Composer patches and Core Image filters allowed in compositions by the plug-in, review “Allowed Patches and Filters” (page 21).

Quartz Composer Web Kit Plug-in Availability

The Quartz Composer Web Kit plug-in is a Web Kit-style internet plug-in, available to Web Kit-based browsers like Safari, OmniWeb, and Shiira. The plug-in is also available to Dashboard widgets since Dashboard uses Web Kit to render the HTML, CSS, and JavaScript files that make widgets.

The Quartz Composer Web Kit plug-in is distributed with the Mac OS X v.10.4.7 Software Update and is available on any Macintosh computer running Mac OS X v.10.4.7 or later. If your Mac is running a version of Mac OS X v.10.4 prior to v.10.4.7, choose Software Update from the Apple menu to update your Mac to the latest version of Mac OS X v.10.4.

Including a Composition in an HTML File

To include a Quartz Composer composition in a webpage or Dashboard widget, you need to include it in an HTML file using the tag, as shown in Listing 1-1.

Listing 1-1 The embed tag for a composition

Many of the attributes included with the tag in Listing 1-1 are standard attributes found in many HTML elements. Four of the attributes in Listing 1-1, however, are noteworthy: type, src, opaque, and above.

■ The type attribute tells the browser loading this element that the content to be displayed is a Quartz Composer composition. To render a Quartz Composer composition, set this attribute to application/x-quartzcomposer. It is important to include this attribute because without it, a browser may try to use another plug-in to render your composition.

■ The src attribute is the uniform resource locator, or URL, to your composition. The URL can specify either a path relative to the HTML file that contains the tag or a fully qualified path.

■ The opaque attribute specifies whether your composition uses transparency. If it does, this attribute should be set to false, meaning that it is not completely opaque.

More HTML attributes are available for the Quartz Composer Web Kit plug-in. Read “Quartz Composer Web Kit Plug-in HTML Attributes” (page 13) to learn more about them.

Note: Certain Quartz Composer patches access local files, services, or hardware. Access to these items from the Quartz Composer Web Kit plug-in is not allowed. To see which patches are allowed within a composition, read “Allowed Patches and Filters” (page 21).

If your composition is self-contained and doesn’t require programmatic interaction via JavaScript, you’re done once you include the composition in your HTML. If your composition has changeable parameters or needs to be controlled via JavaScript, read “Manipulating a Composition using JavaScript” (page 10).

Manipulating a Composition using JavaScript

The Quartz Composer Web Kit plug-in allows for manipulating a composition via a JavaScript API, as shown in Listing 1-2.

Listing 1-2 Changing a composition’s values via JavaScript var composition = document.getElementById("myComposition"); if (composition.playing() == true) { composition.pause(); composition.setInputValue("aPublishedInput", aValue); composition.setInputValue("anotherPublishedInput", anotherValue); composition.play(); }

In Listing 1-2, a composition is obtained from the DOM and its playback status is queried. If the composition is playing, playback is paused, some of the composition’s inputs are altered, and playback is resumed.

Obtaining the composition from the DOM is necessary because it returns the composition object for you to manipulate. Note that the element’s identifier is the same as the id attribute’s value for the composition included in Listing 1-1 (page 10). The rest of these actions are performed using methods found in the Quartz Composer Web Kit plug-in’s JavaScript API.

To learn more about the Quartz Composer Web Kit plug-in’s JavaScript API , read “Quartz Composer Web Kit Plug-in JavaScript API” (page 14).

Quartz Composer Web Kit Plug-in Reference

In “Using the Quartz Composer Web Kit Plug-in” (page 9), you read about including a Quartz Composer composition in HTML (“Including a Composition in an HTML File” (page 10)) and manipulating it via JavaScript (“Manipulating a Composition using JavaScript” (page 10).)

This chapter provides information on the HTML attributes and JavaScript API available when using a Quartz Composer composition within a webpage or Dashboard widget.

Quartz Composer Web Kit Plug-in HTML Attributes

The Quartz Composer Web Kit plug-in provides HTML attributes that affect how a composition is rendered and trigger JavaScript functions on certain events. “HTML Attributes for the Quartz Composer Web Kit Plug-in” lists the attributes specific to the plug-in. To learn more about how to include a composition in a webpage or Dashboard widget, read “Including a Composition in an HTML File” (page 10).

HTML Attributes for the Quartz Composer Web Kit Plug-in

src The uniform resource locator, or URL, to your composition. The URL can specify either a path relative to the HTML file that contains the tag or a fully qualified path.

above A boolean value that specifies whether the composition should render above or below the window displaying a webpage. If above is set to true, no content on the page within the bounds of the composition is shown. If above is set to false, all content on the page within the composition’s bounds is shown over the composition.

This setting is most useful for Dashboard widgets, where a value of false lets you place elements over a composition.

The default value, used if this attribute is not specified, is true.

autoplay A boolean value that specifies whether the composition is played automatically when it’s loaded. If autoplay is set to true, the composition begins playback when it has completed loading. If autoplay is set to false, it doesn’t play automatically.

The default value, used if this attribute is not specified, is true.

opaque A boolean value that specifies whether the composition is opaque or transparent. If opaque is set to true, the composition is rendered with no alpha channel, meaning any transparent areas in the composition are rendered as solid and any elements placed under the composition are not visible. If opaque is set to false, the composition is rendered with an alpha channel, meaning that transparent areas in the composition are rendered using any transparency found in the composition and any elements placed under the composition are visible through transparent areas in the composition.

The default value, used if this attribute is not specified, is true.

maxfps An integer value that specifies the maximum frame rate used when rendering the composition.

The default value, used if this attribute is not specified, is 30.

onload A JavaScript event handler called when the composition is finished loading. The JavaScript function you provide for this event is not passed any arguments when it is called.

onerror A JavaScript event handler called if the composition fails to load. The JavaScript function you provide for this event is passed one argument when it is called; the argument contains a string representing the reason the composition failed to load.

Quartz Composer Web Kit Plug-in JavaScript API

Once you’ve included a composition in a webpage or Dashboard widget, you can manipulate the composition via JavaScript, as discussed in “Manipulating a Composition using JavaScript” (page 10). The JavaScript API provided by the Quartz Composer Web Kit plug-in includes methods for changing a composition’s state and manipulating its published inputs and outputs.

Note: All of the method descriptions described in “Methods” (page 15) assume that the method is called on the composition object as obtained from the DOM. You can obtain the object by calling document.getElementById: var composition = document.getElementById("myComposition"); Obtaining and manipulating the composition is discussed further in “Manipulating a Composition using JavaScript” (page 10).

Methods by Task

Composition metadata ■ “attributes” (page 15) Composition playback ■ “pause” (page 17)

■ “play” (page 18)

■ “stop” (page 19)

Composition status ■ “loaded” (page 17)

■ “paused” (page 18)

■ “playing” (page 18) Pasteboard operations ■ “copyImageToPasteboard” (page 15) Working with published values ■ “getInputValue” (page 15)

■ “getOutputValue” (page 16)

■ “inputKeys” (page 16)

■ “outputKeys” (page 17)

■ “setInputValue” (page 19)

Methods attributes

Returns an array of strings with the composition’s attributes composition.attributes()

Discussion The attributes returned are the composition’s metadata, including its name, copyright, and description values. copyImageToPasteboard

Copies the current context of the composition to the pasteboard composition.copyImageToPasteboard()

Discussion The copyImageToPasteboard method copies the current content visible in the composition to the pasteboard. Use this method in conjunction with an oncopy handler. getInputValue

Returns the value of a published input composition.getInputValue("key")

Discussion The value of key is any of the inputs that you published in Quartz Composer.

If the returned value is a color, an object is returned with red, green, blue, and alpha properties. Each value is a floating point number, on a scale from 0 to 1. Call htmlColor() on the object to return its HTML hexadecimal color value or cssColor() to return its rgba value.

No images are returned when calling getInputValue. See Also “inputKeys” (page 16) “outputKeys” (page 17) “setInputValue” (page 19) “getOutputValue” (page 16)

getOutputValue

Returns the value of a published output

composition.getOutputValue("key")

Discussion The value of key is any of the outputs that you published in Quartz Composer.

No images are returned when calling getOutputValue. See Also “outputKeys” (page 17) “inputKeys” (page 16) “setInputValue” (page 19) “getInputValue” (page 15)

inputKeys

Returns an array of strings with the names of a composition’s published inputs

composition.inputKeys()

Discussion The inputKeys method returns an array of string objects. Each string is the name of one of the composition’s inputs, as published in Quartz Composer.

See Also “setInputValue” (page 19) “getInputValue” (page 15) “outputKeys” (page 17) “getOutputValue” (page 16) loaded

Returns whether the composition is loaded composition.loaded()

Discussion The loaded method returns a boolean value that reflects whether a composition is loaded. See Also “playing” (page 18) “paused” (page 18) outputKeys

Returns an array of strings with the names of a composition’s published outputs composition.outputKeys()

Discussion The outputKeys method returns an array of string objects. Each string is the name of one of the composition’s outputs, as published in Quartz Composer. See Also “getOutputValue” (page 16) “inputKeys” (page 16) “setInputValue” (page 19) “getInputValue” (page 15) pause

Pauses playback of a composition composition.pause()

Discussion The pause method pauses playback of a composition if it was playing. If the composition wasn’t playing, calling this method does nothing.

See Also “play” (page 18) “stop” (page 19)

paused

Returns whether the composition is paused

composition.paused()

Discussion The paused method returns a boolean value that reflects whether a composition is paused and not playing back content. If the composition is stopped (as opposed to paused), paused returns false. See Also “playing” (page 18) “loaded” (page 17)

play

Begins or pauses playback of a composition

composition.play()

Discussion The play method starts playback of a composition if it was stopped or hasn’t played yet, pauses playback if the composition is already playing, and resumes playback if the composition was paused. See Also “pause” (page 17) “stop” (page 19)

playing

Returns whether the composition is playing

composition.playing()

Discussion The playing method returns a boolean value that reflects whether a composition is playing back content. See Also “paused” (page 18) “loaded” (page 17)

setInputValue

Gives the composition the provided value for published input composition.setInputValue("key", value)

Discussion The value of key is any of the inputs that you published in Quartz Composer. If you’re setting an input to a color value, you can pass in:

■ An object like that returned by “getInputValue” (page 15) and “getOutputValue” (page 16), with red, green, blue, and alpha properties

■ An HTML hexadecimal color value, like #FFFFFF

■ An HTML color name, like red or green

■ A CSS rgb or rgba value If the input value can’t be parsed, no change is made. Also, images aren’t allowed as an input value. See Also “inputKeys” (page 16) “outputKeys” (page 17) “getInputValue” (page 15) “getOutputValue” (page 16) stop

Stops playback of a composition composition.stop()

Discussion The stop method stops playback of a composition. This releases all resources associated with the composition and clears its visuals from the page. After calling stop, you can call play to restart the composition. See Also “play” (page 18) “pause” (page 17)

Allowed Patches and Filters

The Quartz Composer Web Kit plug-in only renders certain Quartz Composer patches and Core Image filters within compositions. The allowed patches and filters don’t access information from local files, services, or hardware. The plug-in does not render your composition if it contains a patch or filter not on this list.

Patches and Filters Allowed by the Quartz Composer Web Kit Plug-in

The following patches and filters are allowed in compositions rendered by the Quartz Composer Web Kit plug-in. As a rule, all Image Units and Core Image filters (listed in Quartz Composer’s Patch Library with a bullet) are allowed by the plug-in.

■ Blur - Gaussian Blur

■ Blur - Median

■ Blur - Motion Blur

■ Blur - Noise Reduction

■ Blur - Zoom Blur

■ Color Adjustment - Color Controls

■ Color Adjustment - Color Matrix

■ Color Adjustment - Exposure Adjust

■ Color Adjustment - Gamma Adjust

■ Color Adjustment - Hue Adjust

■ Color Adjustment - White Point Adjust

■ Color Effect - Color Cube

■ Color Effect - Color Invert

■ Color Effect - Color Map

■ Color Effect - Color Monochrome

■ Color Effect - Color Posterize

■ Color Effect - False Color

■ Color Effect - Mask To Alpha

■ Color Effect - Sepia Tone

■ Composite Operation - Addition

■ Composite Operation - Color Blend Mode

■ Composite Operation - Color Burn Blend Mode

■ Composite Operation - Color Dodge Blend Mode

■ Composite Operation - Darken Blend Mode

■ Composite Operation - Difference Blend Mode

■ Composite Operation - Exclusion Blend Mode

■ Composite Operation - Hard Light Blend Mode

■ Composite Operation - Hue Blend Mode

■ Composite Operation - Lighten Blend Mode

■ Composite Operation - Luminosity Blend Mode

■ Composite Operation - Maximum

■ Composite Operation - Minimum

■ Composite Operation - Multiply Blend Mode

■ Composite Operation - Multiply

■ Composite Operation - Overlay Blend Mode

■ Composite Operation - Saturation Blend Mode

■ Composite Operation - Screen Blend Mode

■ Composite Operation - Soft Light Blend Mode

■ Composite Operation - Source Atop

■ Composite Operation - Source In

■ Composite Operation - Source Out

■ Composite Operation - Source Over

■ Controller - Interpolation

■ Controller - Keyboard

■ Controller - LFO

■ Controller - Mouse

■ Controller - Random

■ Controller - Tablet

■ Distortion Effect - Bump Distortion

■ Distortion Effect - Circle Splash Distortion

■ Distortion Effect - Circular Wrap Distortion

■ Distortion Effect - Displacement Distortion

■ Distortion Effect - Glass Distortion

■ Distortion Effect - Glass Lozenge

■ Distortion Effect - Hole Distortion

■ Distortion Effect - Pinch Distortion

■ Distortion Effect - Torus Lens Distortion

■ Distortion Effect - Twirl Distortion

■ Distortion Effect - Vortex Distortion

■ Environment - 3D Transformation

■ Environment - Fog

■ Environment - Lighting

■ Environment - Replicate in Space

■ Environment - TrackBall

■ Geometry Adjustment - Affine Transform

■ Geometry Adjustment - Crop

■ Geometry Adjustment - Lanczos Scale Transform

■ Geometry Adjustment - Perspective Transform

■ Generator - Checkerboard

■ Generator - Constant Color

■ Generator - HSL Color

■ Generator - Image Importer

■ Generator - Image With Movie

■ Generator - Image With String

■ Generator - Lenticular Halo

■ Generator - Plasma Image

■ Generator - Render in Image

■ Generator - RGB Color

■ Generator - Random Generator

■ Generator - Star Shine

■ Generator - String Printer

■ Generator - Stripes

■ Generator - Sunbeams

■ Gradient - Gaussian Gradient

■ Gradient - Linear Gradient

■ Gradient - Radial Gradient

■ Halftone Effect - Circular Screen

■ Halftone Effect - CMYK Halftone

■ Halftone Effect - Dot Screen

■ Halftone Effect - Hatched Screen

■ Halftone Effect - Line Screen

■ Modifier - Color to RGB

■ Modifier - Color to HSL

■ Modifier - Color Transformation

■ Modifier - Image Texturing Matrix

■ Modifier - String Case

■ Modifier - String Components

■ Modifier - String Scanner

■ Modifier - String Truncate

■ Modifier - Structure Key Member

■ Modifier - Structure Index Member

■ Numeric - Conditional

■ Numeric - Counter

■ Numeric - Logic

■ Numeric - Math

■ Numeric - Range

■ Numeric - Round

■ Renderer - Billboard

■ Renderer - Clear

■ Renderer - Cube

■ Renderer - Gradient

■ Renderer - Lines

■ Renderer - Particle System

■ Renderer - Psychedelic

■ Renderer - Sphere

■ Renderer - Sprite

■ Renderer - Teapot

■ Sharpen - Sharpen Luminance

■ Sharpen - Unsharp Mask

■ Stylize - Blend With Mask

■ Stylize - Bloom

■ Stylize - Crystallize

■ Stylize - Edges

■ Stylize - Edge Work

■ Stylize - Gloom

■ Stylize - Height Field From Mask

■ Stylize - Pixellate

■ Stylize - Pointillize

■ Stylize - Shaded Material

■ Stylize - Spot Light

■ Tile Effect - Affine Clamp

■ Tile Effect - Affine Tile

■ Tile Effect - Kaleidoscope

■ Tile Effect - Op Tile

■ Tile Effect - Parallelogram Tile

■ Tile Effect - Perspective Tile

■ Tile Effect - Triangle Tile

■ Tool - Date Formatter

■ Tool - FPS Display

■ Tool - Image Dimensions

■ Tool - Input Splitter

■ Tool - Iterator Variables

■ Tool - Multiplexer

■ Tool - Patch Time

■ Tool - Quartz Composer Info

■ Tool - Rendering Destination Dimensions

■ Tool - Stop Watch

■ Tool - String Length

■ Tool - String Compare

■ Tool - Structure Count

■ Tool - System Time

■ Tool - Core Image Accumulator

■ Tool - JavaScript

■ Transition - Copy Machine

■ Transition - Disintegrate with Mask

■ Transition - Dissolve

■ Transition - Flash

■ Transition - Mod

■ Transition - Page Curl

■ Transition - Ripple

■ Transition - Swipe

Document Revision History

This table describes the changes to Quartz Composer Web Kit Plug-in Programming Guide.

Date Notes

2006-08-07 New document that explains how to use the Quartz Composer plug-in included with Mac OS X v.10.4.7.