The Static Preview

Some of the more simple animations that we’ll be starting to get into in later parts of this series.

A little more animated

Pardon the pun. The following are some more examples of animation in both undocumented and documented code. (Quicktime is required to view these video previews). In this series of tutorials, we’ll be making projects similar to these. (Eventually. This first part, as I mentioned, is an introduction. The next few sections consolidate on this and get increasingly more spectacular, which is to be expected of course.)

CoreGraphics

The Cube Animation Demo using CGSPrivate.h was made in forty lines of written code. The actual application moves back and forth between the tabs, and closes with a nifty animation upon reaching the end of the tabs. After reading this tutorial, you should be able to write a similar app.

Cube Animation Demo

CoreImage

Made using 100% documented CoreImage filters, the CoreImage Animation Demo was written in a little over 60 lines of code. You’ll notice animations like the ripple effect that you get on the Dashboard are able to be implemented using completely documented code. There are also exploding effects, page flip effects and a laser effect! This method is absolutely stunning, but requires more code than the CoreGraphics method. We’ll be visiting CoreImage in the next part of the tutorial.

CoreImage Animation Demo (3.1 MB)

That’s the preview, now let’s get coding!

Animations and Transitions using CoreGraphics

Introducing CGSPrivate.h

Richard J Wareham wrote up an excellent header file for “undocumented CoreGraphics stuff”, and this “Core Graphics” header file (View) will be the basis for all our animations in this first part of the tutorial.

Download the CGSPrivate Header File

/* CGSPrivate.h — Header file for undocumented CoreGraphics stuff. */

/* 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.
 */

#include <Carbon/Carbon.h>


/* These functions all return a status code. Typical CoreGraphics replies are:
    kCGErrorSuccess = 0,
    kCGErrorFirst = 1000,
    kCGErrorFailure = kCGErrorFirst,
    kCGErrorIllegalArgument = 1001,
    kCGErrorInvalidConnection = 1002,
*/

// Internal CoreGraphics typedefs
typedef int       CGSConnection;
typedef int        CGSWindow;

typedef int        CGSValue;

//// CONSTANTS ////

/* Window ordering mode. */
typedef enum _CGSWindowOrderingMode {

    kCGSOrderAbove                =  1, // Window is ordered above target.
    kCGSOrderBelow                = -1, // Window is ordered below target.
    kCGSOrderOut                  =  0  // Window is removed from the on-screen window list.
} CGSWindowOrderingMode;

// Internal CoreGraphics functions.

extern OSStatus CGSGetWorkspace(const CGSConnection cid, int *workspace);

extern OSStatus CGSGetWindowWorkspace(const CGSConnection cid, const CGSWindow wid, int *workspace);

extern OSStatus CGSSetWorkspace(const CGSConnection cid, int workspace);

typedef enum {

    CGSNone = 0, // No transition effect.
 CGSFade,        // Cross-fade.
 CGSZoom,        // Zoom/fade towards us.

 CGSReveal,      // Reveal new desktop under old.
 CGSSlide,       // Slide old out and new in.
 CGSWarpFade,    // Warp old and fade out revealing new.
 CGSSwap,        // Swap desktops over graphically.

 CGSCube,        // The well-known cube effect.
 CGSWarpSwitch   // Warp old, switch and un-warp.
} CGSTransitionType;

typedef enum {

    CGSDown,                // Old desktop moves down.
 CGSLeft,                // Old desktop moves left.
 CGSRight,               // Old desktop moves right.
 CGSInRight,             // CGSSwap: Old desktop moves into screen, 
                            //          new comes from right.

 CGSBottomLeft = 5,       // CGSSwap: Old desktop moves to bl,
                            //          new comes from tr.
 CGSBottomRight,         // Old desktop to br, New from tl.
 CGSDownTopRight,        // CGSSwap: Old desktop moves down, new from tr.

 CGSUp,                  // Old desktop moves up.
 CGSTopLeft,             // Old desktop moves tl.
 CGSTopRight,            // CGSSwap: old to tr. new from bl.
 CGSUpBottomRight,       // CGSSwap: old desktop up, new from br.

 CGSInBottom,            // CGSSwap: old in, new from bottom.
 CGSLeftBottomRight,     // CGSSwap: old one moves left, new from br.
 CGSRightBottomLeft,     // CGSSwap: old one moves right, new from bl.
 CGSInBottomRight,       // CGSSwap: onl one in, new from br.

 CGSInOut              // CGSSwap: old in, new out.
} CGSTransitionOption;

typedef enum {
    CGSTagExposeFade = 0×0002,   // Fade out when Expose activates.

 CGSTagNoShadow       = 0×0008,   // No window shadow.
 CGSTagTransparent   = 0×0200,   // Transparent to mouse clicks.

 CGSTagSticky     = 0×0800,   // Appears on all workspaces.
} CGSWindowTag;

extern OSStatus CGSSetWorkspaceWithTransition(const CGSConnection cid,

    int workspaceNumber, CGSTransitionType transition, CGSTransitionOption subtype, 
    float time);

    
/* Get the default connection for the current process. */
extern CGSConnection _CGSDefaultConnection(void);

typedef struct {
    uint32_t unknown1;

    CGSTransitionType type;
    CGSTransitionOption option;
    CGSWindow wid; /* Can be 0 for full-screen */
    float *backColour; /* Null for black otherwise pointer to 3 float array with RGB value */

} CGSTransitionSpec;

/* Transition handling. */
extern OSStatus CGSNewTransition(const CGSConnection cid, const CGSTransitionSpec* spec, int *pTransitionHandle);

extern OSStatus CGSInvokeTransition(const CGSConnection cid, int transitionHandle, float duration);

extern OSStatus CGSReleaseTransition(const CGSConnection cid, int transitionHandle);

extern OSStatus CGSGetWindowTags(const CGSConnection cid, const CGSWindow wid, 
    CGSWindowTag *tags, int thirtyTwo);

extern OSStatus CGSSetWindowTags(const CGSConnection cid, const CGSWindow wid, 
    CGSWindowTag *tags, int thirtyTwo);

extern OSStatus CGSClearWindowTags(const CGSConnection cid, const CGSWindow wid, 
    CGSWindowTag *tags, int thirtyTwo);

extern OSStatus CGSGetWindowEventMask(const CGSConnection cid, const CGSWindow wid, uint32_t *mask);

extern OSStatus CGSSetWindowEventMask(const CGSConnection cid, const CGSWindow wid, uint32_t mask);

// Get on-screen window counts and lists.
extern OSStatus CGSGetWindowCount(const CGSConnection cid, CGSConnection targetCID, int* outCount); 

extern OSStatus CGSGetWindowList(const CGSConnection cid, CGSConnection targetCID, 
  int count, int* list, int* outCount);

// Get on-screen window counts and lists.
extern OSStatus CGSGetOnScreenWindowCount(const CGSConnection cid, CGSConnection targetCID, int* outCount); 

extern OSStatus CGSGetOnScreenWindowList(const CGSConnection cid, CGSConnection targetCID, 
  int count, int* list, int* outCount);

// Per-workspace window counts and lists.
extern OSStatus CGSGetWorkspaceWindowCount(const CGSConnection cid, int workspaceNumber, int *outCount);

extern OSStatus CGSGetWorkspaceWindowList(const CGSConnection cid, int workspaceNumber, int count, 
    int* list, int* outCount);

// Gets the level of a window
extern OSStatus CGSGetWindowLevel(const CGSConnection cid, CGSWindow wid, 
        int *level);

        
// Window ordering
extern OSStatus CGSOrderWindow(const CGSConnection cid, const CGSWindow wid, 
    CGSWindowOrderingMode place, CGSWindow relativeToWindowID /* can be NULL */);    


// Gets the screen rect for a window.
extern OSStatus CGSGetScreenRectForWindow(const CGSConnection cid, CGSWindow wid, 
        CGRect *outRect);

// Window appearance/position
extern OSStatus CGSSetWindowAlpha(const CGSConnection cid, const CGSWindow wid, float alpha);

extern OSStatus CGSSetWindowListAlpha(const CGSConnection cid, CGSWindow *wids, int count, float alpha);

extern OSStatus CGSGetWindowAlpha(const CGSConnection cid, const CGSWindow wid, float* alpha);

extern OSStatus CGSMoveWindow(const CGSConnection cid, const CGSWindow wid, CGPoint *point);

extern OSStatus CGSSetWindowTransform(const CGSConnection cid, const CGSWindow wid, CGAffineTransform transform); 

extern OSStatus CGSGetWindowTransform(const CGSConnection cid, const CGSWindow wid, CGAffineTransform * outTransform); 

extern OSStatus CGSSetWindowTransforms(const CGSConnection cid, CGSWindow *wids, CGAffineTransform *transform, int n); 


extern OSStatus CGSMoveWorkspaceWindows(const CGSConnection connection, int toWorkspace, int fromWorkspace);

extern OSStatus CGSMoveWorkspaceWindowList(const CGSConnection connection, CGSWindow *wids, int count, 
    int toWorkspace);

// extern OSStatus CGSConnectionGetPID(const CGSConnection cid, pid_t *pid, CGSConnection b);

extern OSStatus CGSGetWindowProperty(const CGSConnection cid, CGSWindow wid, CGSValue key,

    CGSValue *outValue);

//extern OSStatus CGSWindowAddRectToDirtyShape(const CGSConnection cid, const CGSWindow wid, CGRect *rect);
extern OSStatus CGSUncoverWindow(const CGSConnection cid, const CGSWindow wid);

extern OSStatus CGSFlushWindow(const CGSConnection cid, const CGSWindow wid, int unknown /* 0 works */ );

extern OSStatus CGSGetWindowOwner(const CGSConnection cid, const CGSWindow wid, CGSConnection *ownerCid);

extern OSStatus CGSConnectionGetPID(const CGSConnection cid, pid_t *pid, const CGSConnection ownerCid);

// Values
extern CGSValue CGSCreateCStringNoCopy(const char *str);
extern char* CGSCStringValue(CGSValue string);

extern int CGSIntegerValue(CGSValue intVal);

If you do a search for any of these functions in Google or anywhere else, chances are you’ll come up with few, if any results. The reason for this is that CGSPrivate.h is exclusively an internal API for Apple. Regardless, you will see many implementations of this in the Mac environment, with the cube effect during Fast User Switching being quite popular. The header file includes functions for creating, running and discarding animations, which means that there is relatively little work for us to do in order to get our animations happening. You may want to download the file now as we’re going to use it later on in the tutorial.

Apple have neither released, nor endorse the functions CGSPrivate.h. Being undocumented, if Apple change this code then our animations will no longer work; the chance of that happening? Close to zilch.

The functions for workspaces can be ignored, unless you want to write another alternative to Desktop Manager or VirtueDesktops. However, the functions that we will be utilising are mainly CGSNewTransition, CGSInvokeTransition and CGSReleaseTransition. They should be pretty self explanatory, but I’ll go through them just to make sure we’re on the same wavelength.

The Project

Project One - Cube Animation Through an NSWindow subclass

This project will be a simple window with a button on in that invokes a cube animation when clicked. It’s not designed to be useful, rather it will be our first animation project from which we’ll get the knowledge of CGSPrivate and it’s functions. We’ll create apps that actually do something a little on. The best way to learn is by example.
Let’s start up Xcode and create a basic Cocoa Application project.

Call the project whatever you want, I’ve called it “animation”. Now you’ve get a screen with a mostly empty project.

Building the interface

You know the drill, go ahead and bring up MainMenu.nib in Interface Builder, and subclass NSWindow. I’ve called my custom class AnimWindow. Bring up the inspector and add the an action “turn:” which we’ll be using to animate our window.

I expect you know how to create files for the AnimWindow class and make the custom class of the NSWindow to AnimWindow. While you’re at it, you can also drag a button onto the window and connect it to the turn: action we just added. Save and close the nib, and let’s head back to our dear friend Xcode.

I like to move it, move it

We’ve set the interface, but nothing happens when we run our application. It’s time to get our hands dirty and delve into the code.

As I mentioned earlier, we’re going to be using CGSPrivate.h, so download the file and add it to the project. Once the file is added to the target, open up the AnimWindow.m file and import CGSPrivate.h at the top of the file. This allows us to access all the functions found in the CGSPrivate header file. We’ll now add code to the “turn:” action to make the window flip around. Replace the existing blank action with the following code:

- (IBAction)turn  id)sender

{
    // declare our variables
  int handle;
    CGSTransitionSpec spec;
    
    // assign our transition handle
 handle = -1;
    
    // specify our specifications
 spec.unknown1=0;
    spec.type=CGSCube;

    spec.option=CGSLeft; 
    spec.backColour=NULL;
    spec.wid=[self windowNumber];
    
    // Let’s get a connection
 CGSConnection cgs= _CGSDefaultConnection();
    // Create a transition
 CGSNewTransition(cgs, &spec, &handle);

    // Redraw the window
  [self display];

    /* Pass the connection, handle,
    * and duration to apply the animation
    */
    CGSInvokeTransition(cgs, handle, 3);

    /* We need to wait for the transition to finish
    * before we get rid of it, otherwise we’ll get
    * all sorts of nasty errors
    */
    usleep((useconds_t)(3000000));

    /* Finally, release all our variables */

    CGSReleaseTransition(cgs, handle);
    handle=0; 
}

This time, when you Build and Run, the whole window should turn into a cube and spin around when you click the button. That’s a full fledged animation in 15 lines of written code!

We deal with getting rid of the black background later. For now, let’s examine the code we’ve just executed.

Post mortem - What exactly did we do?

The famous cube animation was implemented by a simple subclass of NSWindow, with only 15 lines of written code. We’ll start at the top, and go down through our entire AnimWindow.m file and see what’s going on at each particular instant.

AnimWindow.m

#import “AnimWindow.h”
#import “CGSPrivate.h”

We tell Xcode to include AnimWindow.h, and CGSPrivate.h. As I’ve reiterated a thousand times, CGSPrivate.h contains the definitions for the functions that give us access to the CoreGraphics API for transitions and animations.

@implementation AnimWindow

- (IBAction)turn  id)sender
{
    // declare our variables
  int handle;
    CGSTransitionSpec spec;

    // assign our transition handle
 handle = -1;

Here we simply declare the variables that we will use later on in the method. The integer handle is what we use to refer to our animation object, especially when we have more than one.
We also declare “spec” as a CGSTransitionSpec. This will hold all the options for our transition, such as transition style and direction.
Lastly, we set the handle integer to -1. This can take any value, but usually it is best to leave it 1 or -1.

 // specify our specifications
 spec.unknown1=0;
    spec.type=CGSCube;

    spec.option=CGSLeft; 
    spec.backColour=NULL;
    spec.wid=[self windowNumber];

We set up our transition’s options. CGSTransitionSpec takes the parameters of unknkown1, type, option, backColour and wid.

• Unknown1 is best left at 0 until someone finds out what it’s for.
• Type refers to the type of transition. We’ve put in CGSCube here, but it can be anything from the CGSTransitionOption integers defined in CGSPrivate. For example, you can change it to CGSFlip or CGSSwitch and see what happens when you run the project again.
• Option defines the direction of the transition. Again, all the directions are defined in the CGSPrivate header file. We’ve used CGSRight here, but CGSLeft, CGSUp and CGSDown are all valid directions.
• BackColour (with UK English spelling for some reason) is obviously the colour that the rest of the screen becomes during the transition. This takes an NSArray with three floats to specify the RGB values for the desired color. Sending Null, as in our case defaults to black. We will look at getting rid of the backColour in the second example.
• Wid takes the window number of the NSWindow that we want to apply the transition to. We can get the window number of any window by passing the windowNumber method. In this example, we are applying the transition from the window to itself, so we pass a [self windowNumber];

 // Let’s get a connection
 CGSConnection cgs= _CGSDefaultConnection();

To run any function of CGSPrivate, we need to have a connection to CoreGraphics. Here we define cgs as a _CGSDefaultConnection(). In actual fact, we could omit this step and pass _CGSDefaultConnection() in place of cgs when we do so later on, but doing this step means less typing afterwards and easier to follow code.

    // Create a transition
 CGSNewTransition(cgs, &spec, &handle);

Obviously creates a new transition. We pass on the connection (cgs), the specifications (spec) and the handle. We use the handle to refer to this transition rather than making a pointer to it, like we would most objects in Cocoa.

 // Redraw the window
  [self display];

Forces the window to update. If we don’t redraw the window, the transition will happen, but any changes we wanted to come up will be shown after the transition. Not much of a problem in this sample since we don’t have any content on our window, but we’ll be getting to that.

 /* Pass the connection, handle,
    * and duration to apply the animation
    */
    CGSInvokeTransition(cgs, handle, 3);

Applies the transition. This is the line that causes the whole world to go black and the window to “cube”. We need to pass the cgs connection we made earlier, the handle to identify which transition to invoke and finally the duration in seconds. For a smooth transition, duration is generally best left as an integer between 1 to 10.

 /* We need to wait for the transition to finish
    * before we get rid of it, otherwise we’ll get
    * all sorts of nasty errors
    */
    usleep((useconds_t)(3000000));

    /* Finally, release all our variables */
    CGSReleaseTransition(cgs, handle);
    handle=0; 
}
@end

We need to release the memory used up by our transitions, but if we release anything while the transition is still going, we’ll muck things up. For this reason, we tell the system to wait for the transition to finish by the usleep function. We pass whatever duration we had times 1000000. In our case, 3 * 1000000.

The next line releases the transition from memory. We just need to pass the handle to identify which transition we’re interested in removing, and that’s a wrap! Congratulations, you just pulled off a CoreGraphics animation in 15 lines of written code!

Download Source

Getting Serious

The sample project in this first tutorial was great to demonstrate the use of CGSPrivate, but it could have been written better. In the next part of this series, we’ll be to putting our knowledge to work, and creating an app that actually does something. Stay tuned.

Our Second Project - Setup Assistant (coming soon)

Was this article useful?

Let me know if you found this useful, for motivational purposes. Any feedback or criticism is welcome to improve the scope of this article, and remember, part two is coming soon, which expands on our current knowledge and introduces some new concepts; not to be missed for the world.