Quartz Composer Custom Patch Programming Guide Contents
Total Page：16
File Type：pdf, Size：1020Kb
Quartz Composer Custom Patch Programming Guide Contents Introduction to Quartz Composer Custom Patch Programming Guide 5 Organization of This Document 5 See Also 6 The Basics of Custom Patches 7 A Close Look at the Patch User Interface 7 From Custom Patch Code to Patch User Interface 10 Property and Port Data Types 14 Internal Settings 15 Custom Patch Execution 18 The QCPlugIn Template in Xcode 20 Packaging, Installing, and Testing Custom Patches 22 Writing Processor Patches 24 dotCom: Creating Domain Names 24 MIDI2Color: Mapping MIDI Values to Colors 30 Number2Color: Extending MIDI2Color 38 Packaging Two Custom Patches in a Plug-in 46 Writing Image Processing Patches 48 Getting Images From an Input Port 48 Providing Images for an Output Port 49 Histogram Operation: Modifying Color in an Image 51 Create the Xcode Project 54 Create the Interface 54 Modify the Methods for the PlugIn Class 56 Implement the Methods for the Histogram Object 58 Write the Execution Methods for the Plug-in Class 60 Write Methods for the Output Image Provider 62 Writing Consumer Patches 67 Using OpenGL in a Custom Patch 68 Rotating Square: Rendering a Texture to a Quad 68 2010-03-24 | © 2010 Apple Inc. All Rights Reserved. 2 Contents Glossary 76 Document Revision History 77 2010-03-24 | © 2010 Apple Inc. All Rights Reserved. 3 Figures, Tables, and Listings The Basics of Custom Patches 7 Figure 1-1 A variety of Quartz Composer patches 8 Figure 1-2 The Input Parameters pane for the Teapot patch 9 Figure 1-3 The Settings pane for the Date Formatter patch 10 Figure 1-4 The resulting patch 12 Figure 1-5 The time base setting for the Interpolation patch 13 Figure 1-6 Two sample Settings panes 16 Figure 1-7 The files in a Quartz Composer plug-in project 20 Table 1-1 Data type mappings 14 Listing 1-1 The subclass and properties for a custom string-processing patch 10 Listing 1-2 A routine that returns attributes for property ports 11 Listing 1-3 A routine that returns the custom patch name and description 12 Listing 1-4 Code that declares property instance variables 16 Listing 1-5 An implementation of the plugInKeys method 16 Listing 1-6 Code that implements a view controller 17 Listing 1-7 Code that overrides serialization methods for system configuration data 18 Listing 1-8 Entries in the Info.plist file 22 Writing Processor Patches 24 Figure 2-1 The dotCom custom patch 24 Figure 2-2 The spectrum of RGBA colors produced by the MIDI2Color custom patch 31 Writing Image Processing Patches 48 Figure 3-1 An RGB histogram for an image of a daisy 52 Figure 3-2 A Quartz composition that uses the Histogram Operation custom patch 53 Listing 3-1 Prototype for the vImage histogram function 53 Writing Consumer Patches 67 Figure 4-1 Consumer patches render to a destination 67 Figure 4-2 The Rotating Square custom patch 69 2010-03-24 | © 2010 Apple Inc. All Rights Reserved. 4 Introduction to Quartz Composer Custom Patch Programming Guide A patch is one of the basic elements of the Quartz Composer development tool. Similar to routines in traditional programming languages, patches are base processing units. They execute and produce a result. In Mac OS X v10.4, all patches were built-in to Quartz Composer. Starting in Mac OS X v10.5, you can create custom patches and package them as a Quartz Composer plug-in. After a plug-in is installed in the appropriate directory, the patches contained in it are available to use in the Quartz Composer workspace and by most Quartz Composer clients, and can be used in the same manner that you use built-in patches. This document shows how to create custom patches and package them as Quartz Composer plug-ins. You’ll see how to code a variety of patches from a simple string-processing patch to one that renders using OpenGL. Anyone who uses the Quartz Composer development tool and wants to create a custom patch should read this document. To get the most out of this document, you’ll need to be familiar with Quartz Composer User Guide. You’ll also need to know how to use Xcode to create an Objective-C project. Although Quartz Composer uses OpenGL when it renders, you don’t need to know OpenGL to write a custom patch unless you want to create a custom patch that renders on the GPU. This document shows how to write both non-rendering and rendering custom patches. You can use the properties feature of Objective-C 2.0 when creating a custom patch. If you are unfamiliar with properties, you’ll want to read about them before you start writing custom patches. This feature is a time saver that eliminates the need to write accessor methods. All the examples in this document use properties. See The Objective-C Programming Language. Organization of This Document This document is organized into the following chapters: ● “The Basics of Custom Patches” (page 7) describes how the patches that appear in Quartz Composer relate to the code that generates a custom patch. It provides an overview of the tasks needed to create a custom patch and package it as a plug-in. It also describes the Xcode templates that you can use to write custom patches. ● “Writing Processor Patches” (page 24) shows how to write three patches that process data—one that processes a string, another that converts a numeric value to a color, and another that shows how to configure a parameter that can’t be represented by one of the standard port data types. 2010-03-24 | © 2010 Apple Inc. All Rights Reserved. 5 Introduction to Quartz Composer Custom Patch Programming Guide See Also ● “Writing Image Processing Patches” (page 48) describes how to use input and output image protocols to create a patch that produces an image by operating on two input images. ● “Writing Consumer Patches” (page 67) discusses how to use OpenGL in a custom patch and provides instructions for writing a patch that renders a quad that you can animate. See Also The following resources are valuable to anyone writing a custom patch and packaging it as a Quartz Composer plug-in: ● Several of the sample code projects in /Developer/Examples/Quartz Composer/Plugins are custom patch projects. ● Quartz Composer User Guide describes the development tool and how to use it to create compositions. ● Quartz Composer Programming Guide shows how to perform programming tasks using the Quartz Composer framework. ● Quartz Composer Reference Collection describes all the classes and protocols in the Quartz Composer API. You’ll need to refer to this documentation as you write Quartz Composer custom patches. ● Key-Value Coding Programming Guide contains valuable information for anyone who is unfamiliar this mechanism for getting and setting values. 2010-03-24 | © 2010 Apple Inc. All Rights Reserved. 6 The Basics of Custom Patches A Quartz Composer patch is similar to a routine in a traditional programming language—a patch is a base processing unit that executes and produces a result. A custom patch is one that you write by subclassing the QCPlugIn class. To make a custom patch available in the Quartz Composer patch library, you need to package it as a plug-in—an NSBundle object—and install in the appropriate directory. If you’d like, you can package more than one custom patch in a plug-in. You don’t need to create a user interface for a custom patch. When Quartz Composer loads your plug-in, it creates the user interface automatically for each custom patch in the plug-in so that custom patches have the same look in the workspace as the patches that are built in to Quartz Composer. This chapter provides a discussion of custom patches and gives an overview of the tasks you need to perform to create a custom patch. You’ll see which aspects of your code give rise to the user interface for a custom patch. By the end of the chapter you should have a fairly good idea of how to get started writing your own custom patches. Then you can read “Writing Processor Patches” (page 24) and “Writing Consumer Patches” (page 67) to find out how to write specific kinds of patches. A Close Look at the Patch User Interface Patches in Quartz Composer all have the same basic look and feel, as you can see in Figure 1-1. The patch name is at the top of the patch, in the patch title bar. Input ports are on the left side of the patch and output ports are on the right side. Many provider patches don’t have input ports because they get data from an outside 2010-03-24 | © 2010 Apple Inc. All Rights Reserved. 7 The Basics of Custom Patches A Close Look at the Patch User Interface source, such as a mouse, keyboard, tablet, or MIDI controller. Consumer patches don’t have output ports because they render data to a destination. Processor patches have one or more input ports and one or more output ports. Figure 1-1 A variety of Quartz Composer patches 2010-03-24 | © 2010 Apple Inc. All Rights Reserved. 8 The Basics of Custom Patches A Close Look at the Patch User Interface The inspector provides access to the patch parameters. The Input Parameters pane contains the same parameters represented by the input ports. It provides the option to manually adjust input values instead of supplying values through the input ports. Compare the Teapot patch shown in Figure 1-1 (page 8) with Figure 1-2.