There’s a subversion repository as well if you’re keen to stay up to date.

CTGradient contains an incredible diversity of built-in gradients, gradient styles, and methods for creating fancy rainbows, radial gradients, linear gradients, aqua gradients, and a number of other interesting class and instance methods. It allows you to dynamically alter gradients by adding or removing colors, changing the level of transparency, filling NSRects or NSBezierPaths, rotating the gradient, etc. For demonstration purposes, all these features are excellent. For production, this is a nightmare.

CTGradient.m weighs in at over 1300 lines of code.

Ignoring Mr. Weider’s unique style of formatting, take a look through the code. If you’re putting this class in an application, you can immediately remove over a thousand lines. Just like that. But if you take some time to understand what’s going on, you can optimize this thing till it runs like a Ferrari.

You’ll notice Trimmit uses a gradient background for it’s window. Let’s cut down CTGradient until it matches the level of optimization of Trimmit’s gradient code.

Clear the junk

Firstly, let’s remove the methods we know for sure we won’t need. Remove the following methods completely from both the interface and the implementation (scroll down for more):

// We don't need the preset gradients

+ (id)dividerGradient;
+ (id)statusBarGradient;
+ (id)aquaSelectedGradient;
+ (id)aquaNormalGradient;
+ (id)aquaPressedGradient;
+ (id)unifiedSelectedGradient;
+ (id)unifiedNormalGradient;
+ (id)unifiedPressedGradient;
+ (id)unifiedDarkGradient;
+ (id)sourceListSelectedGradient;
+ (id)sourceListUnselectedGradient;
+ (id)rainbowGradient;
+ (id)hydrogenSpectrumGradient;

// We won't make any drastic modifications to the gradient once created

- (CTGradient *)gradientWithAlphaComponent:(float)alpha;
- (CTGradient *)addColorStop:(NSColor *)color atPosition:(float)position;
- (CTGradient *)removeColorStopAtIndex:(unsigned)index;
- (CTGradient *)removeColorStopAtPosition:(float)position;
- (CTGradientBlendingMode)blendingMode;
- (NSColor *)colorStopAtIndex:(unsigned)index;
- (NSColor *)colorAtPosition:(float)position;

// Now we don't need to conform to the NSCopying and NSCoding protocols

- (id)copyWithZone:(NSZone *)zone;
- (void)encodeWithCoder:(NSCoder *)coder;
- (id)initWithCoder:(NSCoder *)coder;

// We only need to fill a simple NSRect

- (void)drawSwatchInRect:(NSRect)rect;
- (void)radialFillRect:(NSRect)rect;
- (void)fillBezierPath:(NSBezierPath *)path angle:(float)angle;
- (void)radialFillBezierPath:(NSBezierPath *)path;

// Remove the entire (Private) category;
// but leave -addElement:

- (void)_commonInit;
// move setBlendingMode code into init
- (void)setBlendingMode:(CTGradientBlendingMode)mode;
- (CTGradientElement *)elementAtIndex:(unsigned)index;
- (CTGradientElement)removeElementAtIndex:(unsigned)index;
- (CTGradientElement)removeElementAtPosition:(float)position;

The following C functions are now unused:

static void chromaticEvaluation(void *info, const float *in, float *out);
static void inverseChromaticEvaluation(void *info, const float *in, float *out);
static void transformRGB_HSV(float *components);
static void transformHSV_RGB(float *components);
static void resolveHSV(float *color1, float *color2);

And also remove the following from the header:

typedef enum  _CTBlendingMode
    {
    CTLinearBlendingMode,
    CTChromaticBlendingMode,
    CTInverseChromaticBlendingMode
    } CTGradientBlendingMode;

Remove the <protocols> and unnecessary instance variables so the interface looks like this:

@interface CTGradient : NSObject {
    CTGradientElement* elementList;
    CGFunctionRef gradientFunction;
}
+ (id)gradientWithBeginningColor:(NSColor *)begin endingColor:(NSColor *)end;
- (void)fillRect:(NSRect)rect angle:(float)angle;
- (void)addElement:(CTGradientElement *)newElement;
@end

Before we go further, we’ll need to take a detour and fix the remaining code so that it compiles. That’s easy enough - just remove any references to code we’ve removed.

If you’ve been following along, your CTGradient should now look like this (also made it readable!).

In a few short minutes, we’re down from more than 1300 to a little over 200 lines.

It gets better.

Optimize it

First stop, fillRect:angle:. Since the gradient for Trimmit’s window only runs vertically (angle 90), we can straight away take out the angle argument, and also cut the entire if / else structure with the angle down to the two lines that are under the if(angle == 90). Ah, much better.

Now things start getting a teeny bit more complex - and fun.

The CTGradient code is written so that one can have many different color stops. The CTGradientElement struct has a nextElement which points to the next CTGradientElement and the position of the current element is stored under the float position. However, we need just two - the starting and ending shades.

Let’s take a look at cutting the multiple elements down to just two.

The addElement: method has a lot of looping to insert the element at the correct place. However, since we know that we only ever need two, we can cut it down to this:

- (void)addElement:(CTGradientElement *)newElement {
    if(elementList) {
        // elementList exists, add second element
        elementList->nextElement = malloc(sizeof(CTGradientElement));
        *(elementList->nextElement) = *newElement;
        elementList->nextElement->nextElement = 0;
    } else {
        // no elements - add first element
        elementList = malloc(sizeof(CTGradientElement));
        *elementList = *newElement;
        elementList->nextElement = 0;
    }
}

Similarly with dealloc,

- (void)dealloc {
    CGFunctionRelease(gradientFunction);
    free(elementList->nextElement);
    free(elementList);
    [super dealloc];
}

While we’re at it, let’s clean up init as well:

- (id)init {
    if(self = [super init]) {
        CGFunctionCallbacks evaluationCallbackInfo = {0 , &linearEvaluation, 0};
        static const float input_value_range[2] = { 0, 1 };
        static const float output_value_ranges[8] = { 0, 1, 0, 1, 0, 1, 0, 1 };
        gradientFunction = CGFunctionCreate(&elementList, 1, input_value_range, 4, output_value_ranges, &evaluationCallbackInfo);
    }
    return self;
}

Now we head to the linearEvaluation function. info passed in refers to elementList (see the CGFunctionCreate call). Again, since we know that we’ll only ever have two elements we can reduce it to:

void linearEvaluation (void *info, const float *in, float *out) {
    float position = *in;

    CTGradientElement *color1 = *(CTGradientElement **)info;
    CTGradientElement *color2 = color1->nextElement;

    out[0] = (color2->red - color1->red)*position + color1->red; 
    out[1] = (color2->green - color1->green)*position + color1->green;
    out[2] = (color2->blue - color1->blue)*position + color1->blue;
    out[3] = (color2->alpha - color1->alpha)*position + color1->alpha;
}

And now we can finally remove the lines from +gradientWithBeginningColor:endingColor: where the positions are set, and also remove the position float from the CTGradientElement struct.

We’re now down to a little over 100 lines. Your CTGradientElement.m should now be looking something like this. Going well, but let’s take things up a notch.

For Trimmit’s background, we’re not interested in the red, green, blue and alpha components - we just need a grayscale shading. This is the most fun part.

Instead of float red, green, blue, alpha; in the CTGradientElement struct, we can have just float shade;.

Now, during init we have:

CGFunctionCallbacks evaluationCallbackInfo = {0 , &linearEvaluation, 0};
static const float input_value_range[2] = { 0, 1 };
static const float output_value_ranges[8] = { 0, 1, 0, 1, 0, 1, 0, 1 };
gradientFunction = CGFunctionCreate(&elementList, 1, input_value_range, 4, output_value_ranges, &evaluationCallbackInfo);

The third argument, input_value_range is the domain. This gets passed into linearEvalution through *in.This is the independent variable. When we’re drawing the gradient, linearEvaluation is called with *in (the domain) starting at the first value of input_value_range and ending up at the second. So, something like 0.000, 0.001, 0.002 … 0.998, 0.999, 1.000. The function’s job is to set the the color components for each given value of the domain.

The first optimization we can make here is to return only one channel instead of four. This changes it to:

- (id)init {
    if (self = [super init]) {
        CGFunctionCallbacks evaluationCallbackInfo = {0, &linearEvaluation, 0};
        static const float range[2] = {0, 1};
        static const float domain[2] = {0, 1};
        gradientFunction = CGFunctionCreate(&elementList, 1, domain, 1, range, &evaluationCallbackInfo);
    }
    return self;
}

This change impacts back on the linearEvaluation function - now it only needs to return one channel:

void linearEvaluation (void *info, const float *in, float *out) {
    CTGradientElement *color1 = *(CTGradientElement **)info;
    out[0] = (color1->nextElement->shade - color1->shade)*(*in) + color1->shade;
}

And don’t forget +gradientWithBeginningColor:endingColor:. We improve performance here, as we only need the shade - not a color. We can rename it to something appropriate.

+ (id)gradientWithBeginningShade:(float)begin endingShade:(float)end {
    id newInstance = [[[self class] alloc] init];
    CTGradientElement color1, color2;

    color1.shade = begin; color2.shade = end;

    [newInstance addElement:&color1];
    [newInstance addElement:&color2];
    return [newInstance autorelease];
}

Now we’re only returning one grayscale channel. But hold on, we’re still in the RGB colorspace! That’s easily fixed. In fillRect:, replace:

#if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_4
    CGColorSpaceRef colorspace = CGColorSpaceCreateWithName(kCGColorSpaceGenericRGB);
#else
    CGColorSpaceRef colorspace = CGColorSpaceCreateDeviceRGB();
#endif

with:

CGColorSpaceRef colorspace = CGColorSpaceCreateDeviceGray();

CGColorSpaceCreateDeviceGray is device-dependent on Mac OS X 10.3 and below, but starting from Tiger, it’s now device-independent which is good in terms of appearance.

While we’re in fillRect:, we can also make a few more improvements:

- (void)fillRect:(NSRect)rect {
    CGContextRef currentContext = [[NSGraphicsContext currentContext] graphicsPort];
    CGContextSaveGState(currentContext);
    CGColorSpaceRef colorspace = CGColorSpaceCreateDeviceGray();
    CGContextClipToRect(currentContext, *(CGRect *)&rect);
    CGShadingRef myCGShading = CGShadingCreateAxial(colorspace, CGPointMake(0, 0), CGPointMake(0, NSMaxY(rect)), gradientFunction, 0, 0);
    CGContextDrawShading(currentContext, myCGShading);

    CGShadingRelease(myCGShading);
    CGColorSpaceRelease(colorspace);
    CGContextRestoreGState(currentContext);
}

I moved the startPoint and endPoint CGPoints straight into the CGShadingCreateAxial call. Also, we only ever fill the whole view with the gradient, so just put in 0 instead of using NSMinX and NSMinY. We could replace the CGPointMake(0, 0) with (CGPoint){0,0}, but I’m not sure if that’d be noticeably faster.

Our code is at a lean 80 lines. Now for the biggest change yet.

Heading back to dear old linearEvaluation. Look at this line:

out[0] = (color1->nextElement->shade - color1->shade)*(*in) + color1->shade;

What’s happening here? Think about it like this:

Essentially, we’re just "graphing" a straight line:

y = mx + c

where x is the position, *in, and y is the shade we return (out[0]), and c is the initial shade.

Since our x value only goes from 0 to 1 (see domain in CGFunctionCreate), at x = 0, we will have y = c. At x = 1, we’ll have y = m + c.

So we only need the start shade as our *info value, since we can have m as the difference between the final and initial shades. Let’s effect this in our code.

We can get rid of the CTGradientElement struct. Remove from the header:

typedef struct _CTGradientElement {
    float shade;
    struct _CTGradientElement *nextElement;
} CTGradientElement;

Instead of the struct, we’ll use a single shade instance variable. We don’t need the +gradientWithBeginningShade:endingShade: anymore, nor do we need -addElement:. So our interface now looks like this:

@interface CTGradient : NSObject {
    float shade;
    CGFunctionRef gradientFunction;
}
- (void)fillRect:(NSRect)rect;
@end

From the implementation, we can remove the free calls in dealloc as well as the whole of +gradientWithBeginningShade:endingShade: and addElement:. We can set the shade in the init method (and replace &elementList with &shade), and change the linearEvaluation function to:

void linearEvaluation (void *info, const float *in, float *out) {
    out[0] = *(float*)info + (*in)*0.1;
}

The 0.1 is what determines how much brighter the top of the gradient is (it’s the m value of our straight line) compared to the bottom.

But since the (*in)*0.1 will go from 0 to 0.1 (as *in goes from 0 to 1), we can actually change the domain we declare for CGFunctionCreate to {0, 0.1} and have our function as:

void linearEvaluation (void *info, const float *in, float *out) {
    out[0] = *(float*)info + *in;
}

You can now add accessors for shade if you need to change the shade of the gradient or you could even have an initWithShade: method. In fact, here’s an Xcode project with the gradient.

Lean Gradient Xcode Project

We now have our gradient code down from 1300 lines to just over 30 lines.

We’ve almost reached a similar level of optimization to Trimmit’s gradient. There will be further optimizations you can make, but it depends on what you’re using the gradient for. For example, if the gradient you’re drawing is always the same, you can optimize further by removing the shade instance variable and all references to it, and hardcode the value into the linearEvaluation function.

Getting to the end of this article, you’re probably thinking that it would be a bit of a waste to use CTGradient if by the time you optimize it for your application, it doesn’t resemble the original at all. And you’re quite right. The documentation already shows you how to draw gradients, yet the number of applications using CTGradient - the whole 1300 lines of it - is astonishing.

Please: When you use other people’s code, don’t put it in without a thought. Go through it, understand it, and optimize it for your specific need. For the better performance and reduced RAM usage, computers will thank you.

I’ve recently started using Inbox for organizing and collecting all my various projects as well as study materials and schedules. Although it took a while for me to get used to the whole GTD concept, I now use the application constantly.

Midnight Inbox implements David Allen’s GTD approach

One of the great things about Inbox is that it looks so good. Good enough to forgive make up for its relatively frequent crashes. The interface is really well designed, keeping in line with many of the Mac metaphors while adding a few unobtrusive features that are generally easy to work out.

It’s clear this is a great application. It has major potential and version 2.0 looks exciting. Congrats to the developers.

Going through the contents of the application, I found CGS.framework and thought, “Interesting. They’re using Core Graphics”. It didn’t occur to me that I released a framework with the exact same name. Well, I’ve finally realized that one of my favorite apps is possibly using this framework and … [speechless].

This is the first application (to my knowledge) to use that particular framework, and only the second to use code that I’ve posted. (Logan Rockmore’s Assignment Planner was the first, using the AnimatingTabView).

I’ve never used another GTD program before, but after trying this app, I doubt I’ll need to. Go check out the fantabulous Midnight Inbox and get things done with style.

It uses Core Graphics and Core Image APIs for the transition effects to animate the window / view, which probably needs a minimum of Mac OS X Tiger. The full source code is available.

Standard Animation Effects

Quicksilver adds a category to the NSWindow class to allow for some pretty cool effects. The following should be pretty self-explanatory:

-(void)pulse:(id)sender;
-(void)flare:(id)sender;
-(void)shrink:(id)sender;
-(void)fold:(id)sender;

What these methods essentially mean, is that you can pulse, flare, shrink or fold any window you have a reference to in a plugin - whether it’s an interface or dialog or something completely different. Eg, just call [window shrink:nil] and watch that NSWindow shrink down to nothing, or [window flare:nil] to make it burst away!

Private Core Graphics Animations

Quicksilver also adds methods to use private Core Graphics transitions for instances of NSWindow or its subclasses. The main method is defined something like:

- (void) displayWithTransition:(CGSTransitionType)type option:(CGSTransitionOption)option duration:(float)duration;

The transitions you have access to are fade, zoom, reveal, slide, warp-fade, swap, warp-switch and the famous cube animation. You can use them on any window, for example:

[window displayWithTransition:CGSCube option:CGSLeft duration:1.3];

To learn more about Core Graphics transitions, see the Core Graphics ebook, or play around with the Core Transitions Framework.

Quicksilver’s CGSPrivate.h file is missing CGSFlip, but you can run the Dashboard-style flip effect by using the integer 9.

Quicksilver’s own animations

Alcor has used various techniques to write several very interesting animation effects into Quicksilver. You’ll be familiar with some of these (just watch the Primer interface activate and deactivate) but for whatever reason, many of these bizarre animations never made into an interface. They’re really very clever. I’ve played around with some of these:

• QSGrowEffect
• QSShrinkEffect
• QSSlightGrowEffect
• QSSlightShrinkEffect
• QSBingeEffect
• QSPurgeEffect
• QSExplodeEffect
• QSExtraExtraEffect
• QSShakeItLikeAPolaroidPictureEffect
• QSBoobTubeEffect
• QSVExpandEffect
• QSVillainousKryptonianEffect
• QSMMBlowEffect
• QSLudicrousSpeedEffect

Very interesting to look at, but how does one use these effects?

As we are dealing with Quicksilver, the solution is (as expected) very elegant. There are very simple methods to set a show, hide or execute effect for a window. These methods don’t even require an explanation; they’re so simple:

// Effect for showing the QSWindow
[window setShowEffect:[NSDictionary dictionaryWithObjectsAndKeys:@"QSSlightGrowEffect",@"transformFn",@"show",@"type",[NSNumber numberWithFloat:2.0],@"duration",nil]];

// Effect for hiding the QSWindow
[window setHideEffect:[NSDictionary dictionaryWithObjectsAndKeys:@"QSSlightShrinkEffect",@"transformFn",@"hide",@"type",[NSNumber numberWithFloat:2.0],@"duration",nil]];

// The "execute" effect is slightly different:
[window setWindowProperty:[NSDictionary dictionaryWithObjectsAndKeys:@"QSExplodeEffect",@"transformFn",@"hide",@"type",[NSNumber numberWithFloat:1.5],@"duration",nil] forKey:kQSWindowExecEffect];

Easy!

Sample plugin

I don’t dare mention all this private goodness and not even provide a demonstration. I’ve created an “Effects” plugin that will allow you to change the activate, deactivate and execute effects for any Quicksilver interface temporarily to play around with the effects. Just for good measure, I’ve also thrown in an action that lets you explore Core Graphics transitions as well.

This is not really a bona fide Quicksilver plugin; while it does let you have some fun with the effects, it’s not very user-friendly and doesn’t save your configuration. If these animations prove to be popular, then I’ll write a proper plugin to let you configure the effects more easily (probably through a preference pane) and remembers your settings.

Download Quicksilver Effects Plugin

Usage

Type in the name of the effect you want, then use “Set Hide Effect”, “Set Show Effect” or the “Set Exec Effect” action. The list of effects is given above; just type one in and run the relevant action.

To run a Core Graphics transition, type in the name of the transition, and use the “Run CoreGraphics Transition” action. You can optionally specify a direction in the indirect selector. (You can enter text in the direct and indirect selectors by pressing the period “.” key)

For example

• “QSBingeEffect” -> Set Show Effect
• “QSPurgeEffect” -> Set Hide Effect
• “QSExplodeEffect” -> Set Exec Effect
• “flip” -> Run CoreGraphics Transition
• “slide” -> Run CoreGraphics Transition -> “up”
• “swap” -> Run CoreGraphics Transition -> “inout”

Pictures show how to use the effects plugin. Actual animations are not shown.

Quicksilver has many such hidden surprises and nifty time-saving methods; it’s so well thought out and full of these amazing gems!

What do you think about these animations? Be sure to let me know if you’d like a proper, more user-friendly plugin to use these effects.

The function CGSSetWindowWarp is part of the private portion of Core Graphics. Although its just as obscure and undocumented as the rest of the private parts of the framework, there has been some discovery and progress into its usage. Erling Ellingsen has written (a while ago) about CGSSetWindowWarp on his blog, and he also shows some very interesting screenshots of what’s possible.

So, how do you use this incredible function in your Cocoa (or Carbon) application?

CGSSetWindowWarp Usage

Including the header

Whenever you use private Core Graphics functions, you generally need to #import either one of CoreGraphicsServices.h or CGSPrivate.h (available for download with my Core Graphics ebook). However, if you’re not interested in using the rest of the Core Graphics API, you can get away with simply adding the following to your main class’ header file:

typedef struct CGPointWarp {
        CGPoint local;
        CGPoint global;
}CGPointWarp;

typedef int CGSConnectionID;
typedef int CGSWindowID;

extern CGSConnectionID _CGSDefaultConnection();

extern CGError CGSSetWindowWarp(CGSConnectionID, CGSWindowID, int w, int h, CGPointWarp mesh[w][h]);
extern OSStatus CGSGetScreenRectForWindow(CGSConnectionID cid, CGSWindowID wid, CGRect *outRect);
extern OSStatus CGSGetWindowBounds(CGSConnectionID cid, CGSWindowID wid, CGRect *bounds);

As you’ve probably guessed, the function that actually applies the mesh transform is CGSSetWindowWarp. You can create a mesh in two different ways.

Creating the mesh

To create a mesh, we need to specify how many points we’re going to take for our grid length-wise and width-wise. Something like this:

#define H 64
#define W 5

We’ll also need to refer to the position and size of the frame so the following code in the method you’re writing this will give us access to the frame of the NSWindow:

CGRect frame;
CGSGetWindowBounds(cid, [window windowNumber], &frame);

The use of CGSGetWindowBounds ensures we get the apparent frame rather than just the frame computed by our code as we’ll be applying various transformations.

The first way to create a mesh requires more labor (yes, its tiring to code) but gives you greater control over the mesh and the transformations applied to the NSWindow.

Manual mesh

CGPointWarp meshes[H][W] =
{
{ {{0, 0},{10, 10}}, {{200,0},{180,12}} },
{ {{0, 50},{0,50}}, {{200,50},{200,50}} },
{ {{0,100},{0,100}}, {{200,100},{200,100}} },
{ {{0,150},{0,150}}, {{200,150},{200,150}} },
{ {{0,200},{0,200}}, {{200,200},{200,200}} },
};

Here, you specify firstly the coordinates of the point which you’re taking, and where you want to move that point. The first line in the above code takes (0,0) and moves it to (10,10) and moves (200,0) to (180,12). However, the first set of coordinates are local coordinates, and the second set are global. (ie., the first set are on the plane of the window, while the second set use the screen as the plane. This is to allow the window to be stretched out beyond the scope of the current frame.) We could solve this issue by using:

int x = frame.origin.x;
int y = frame.origin.y;
CGPointWarp meshes2[H][W] =
{
{ {{0, 0},{x, y}}, {{200,0},{x+200,y}} },
{ {{0, 50},{x,y+50}}, {{200,50},{x+200,y+50}} },
{ {{0,100},{x,y+100}}, {{200,100},{x+200,y+100}} },
{ {{0,150},{x,y+150}}, {{200,150},{x+200,y+150}} },
{ {{0,200},{x,y+200}}, {{200,200},{x+200,y+200}} },
};

The preceding code just warps the window of size 200×200 to its current position so no change is observable. If we wanted to stretch out the middle of the window horizontally, we could use a mesh in the form:

int x = frame.origin.x;
int y = frame.origin.y;
CGPointWarp stretchThroughMiddleMesh[H][W] =
{
{ {{0, 0},{x, y}}, {{200,0},{x+200,y}} },
{ {{0, 50},{x-10,y+50}}, {{200,50},{x+200+10,y+50}} },
{ {{0,100},{x-20,y+100}}, {{200,100},{x+200+20,y+100}} },
{ {{0,150},{x-10,y+150}}, {{200,150},{x+200+10,y+150}} },
{ {{0,200},{x,y+200}}, {{200,200},{x+200+10,y+200}} },
};

We’ve taken the side where x=0 and moved x further back along the middle, and done the opposite on the opposite side (where x=200). This results in the NSWindow being warped to have a bulge in the middle.

Again, this would only look like the screenshot on a window with a height and width of 200. For a window that’s a different size, you’ll need to change the values to match the height and width of the window. For the y-values in the mesh (x, x+50, x+100, etc. in the different rows), the numbers are determined by how many points you’ve taken (your value for H) and the width of the window. The general formula you would use would be x + ( frame.size.height / (W-1) ). You’ll see this more clearly in the second method.

Mesh through iterative formulae

The second method to create a mesh is to run a loop to configure your individual points. Here’s a basic example that creates a mesh that would be identical to the current state of the window:

int h;
int w;
CGPointWarp meshes[H][W];
for (h = 0; h < H; h++) {
    for (w = 0; w < W; w++) {
        CGPointWarp point;
        point.local.x = w * (frame.size.width / (W - 1));
        point.local.y = h * (frame.size.height / (H - 1));
        point.global.x = point.local.x + frame.origin.x;
        point.global.y = point.local.y + frame.origin.y;

        meshes[h][w] = point;
    }
}

Obviously we want to transform the window somehow. We need to apply some sort of mathematical function to the points to make them deviate from their original positions or coordinates. (This is the part where you start to wish you’d paid more attention in math class).

Lets say we want to skew the window using the x-axis. Each successive x-value needs to be greater than the previous one. Since we’re looping through each point, at any time in the inner for loop, the values of the current point are (w,h). (In Cartesian coordinates the x value is first, followed by the y value) In order to increase each successive value for x, we need to add something. But, we need to add more than what we did the previous time. The easiest way to do this without adding any new variables is to use the value that we’re incrementing each time - the x value itself. So, for a skewed window, we have the following mesh:

int h;
int w;
CGPointWarp meshes[H][W];
for (h = 0; h < H; h++) {
    for (w = 0; w < W; w++) {
        CGPointWarp point;
        point.local.x = w * (frame.size.width / (W - 1));
        point.local.y = h * (frame.size.height / (H - 1));
        point.global.x = point.local.x + frame.origin.x + 15*h;
        point.global.y = point.local.y + frame.origin.y;

        meshes[h][w] = point;
    }
}

The skewed window would like this when the mesh was applied:

Applying the mesh

The transform mesh was really the hard part. Applying the transformation mesh (or grid) to a window is as easy as:

CGSSetWindowWarp(_CGSDefaultConnection(), [window windowNumber], W, H, meshes);

The possibilities of this are really amazing. I’ve always wanted to write an NSWindow subclass that bent and reduced in opacity as it was dragged, imitating XGL. With CGSSetWindowWarp and Core Graphics, I’m sure it’ll be a breeze. Or what about an virtual universe-style Finder cross Desktop, sort of like 3DOSX? You could even imitate other effects with this, such as the cube, but still get live updating in your windows - a limitation present in the Core Graphics transition effects.

For a source code, and a further explanation, see Kevin Ballard’s post on the subject of CGSSetWindowWarp.

Did you find this useful? Or do you have any other method that you use for eye candy?

Look familiar? The Mac OS X genie effect is a patented effect that is set as the default minimizing effect for windows in the Mac environment. Dating back to 2004, this animation involves a complex transformation of the source window in order to render it correctly on screen. Apple have not documented this feature for use in third party applications in Cocoa (It is available in Carbon). It is something else that makes up the private portion of the Core Graphics framework. However, keen developers like yourself can play with / use / abuse this awesome effect all you like.

The genie effect can be run using the private Core Graphics function CGSCreateGenieWindowAnimation. The requisites for this: A window to use the effect on, a connection to Core Graphics, and another window into which the source window goes. As an example, take a look at this code:

- (void)doGenieFrom:(NSWindow*)source to:(NSWindow*)destination backwards:(BOOL)backwards {
    CGSAnimationRef ref;
    int err;

    err = CGSCreateGenieWindowAnimation(_CGSDefaultConnection(), [source windowNumber], [destination windowNumber], &ref);

    if (backwards) {
        [source orderWindow:NSWindowBelow relativeTo:[destination windowNumber]]; /* No different to makeKeyAndOrderFront]*////
        [source setExcludedFromWindowsMenu:NO];
        [source flushWindow];
    }    
    
    if (0 == err) {
        float x;
        
        for (x = (backwards ? 1.0 : 0.0); (backwards ? (x >= 0.0) : (x <= 1.0)); (backwards ? (x -= 0.01) : (x += 0.01))) {            
            err = CGSSetWindowAnimationProgress(ref, x);
            
            usleep(1000);
        }
        
        err = CGSReleaseWindowAnimation(ref);
        
    }
    
    if (backwards) {
        [destination setExcludedFromWindowsMenu:YES];
    [source makeKeyAndOrderFront:self];
        [source setExcludedFromWindowsMenu:NO];
    } else {
        [source setExcludedFromWindowsMenu:YES];
        
        [destination makeKeyAndOrderFront:self];
        [destination setExcludedFromWindowsMenu:NO];
    }
}

How easy is that? Of course, this only compiles if you #import a header file that defines the Core Graphics private functions. (ie, just add this file to your Xcode project, then add a #import “coregraphicsservices.h” line at the top of the page where you want to use private CGS functions).

In the age of smoking windows, flashing views and an unofficial redefinement of the HIG by developers, the genie animation can finally come out to play.

If you’re enthralled by the genie, here is a list of cool stuff you can do on your mac regarding minimizing windows / expose.

Thoughts about this post? Add a comment, I value your feedback.

Play with fire.

Download

Feedback and criticism encouraged and appreciated.

© 2006 Ankur Kothari

All the PPC / Intel specific bugs have been found, caught, and eradicated. The framework should now be ready for developer consumption for use in commercial apps, or for experimentation and utter bewilderment. Be amazed. Be very amazed, and download the framework straight from here or read and download it from the original post.

Now works on all architectures, and without hiccups!

Can’t get enough of window transitions? Love a little eye candy? Well, you’re in luck. The Core Graphics Framework and Xcode Project Template make adding the fantastic Core Graphics function to your app a breeze. In fact, it’s even more complete than the tutorial, and already has more features in it before you write a single line of code! It doesn’t stop there, however. This framework powerful enough to use the genie effect. That’s right. That awesome Mac OS X transform you can get when you minimize an application. Core Graphics contains a wealth of resources. You really have to check it out.

Point. Click. Zoom!

The CGS Framework is a an implementation of transitions, transforms and everything Core Graphics. It includes the definitions and implementations for the methods, so that using a transition or transform is as simple as calling a single method! For example, scaling a window is as simple as a “- scale: about:” call on the window, and rotating it just requires a single “- rotate: about:”. In the same way, Core Graphics is laid bare with this framework, for you to utilize at your pleasure!

Don't lift a finger

The framework does all the work for you, but even then, it gets simpler. Source for a sample app is included which means that you can create Core Graphics projects straight away by building on top of it. This saves you, the developer time in adding and linking the Framework, and reading and implementing the Core Graphics class in Interface Builder, as well as adding the framework to your project. A single double-click on the sample project and it’s all done for you. What more could you ask? Download a copy and check it out today. You’ll be surprised how powerful it is.

Gimme already!

Now a universal binary for your developing pleasure!

CGS Framework + Sample App

Once downloaded, open CoreGFX.app to view some of the possible effects. You can copy the source folder to hard drive if you need to build a Core Graphics enabled app. Enjoy the wonderfulness, and I hope you have fun!

Any queries, fire away.

Make sure you understand that some of the functions of Core Graphics used in this framework are undocumented, internal APIs that Apple haven’t released. (Calm down. It’s not illegal). Having said that, apps like Quicksilver would be quite bland without the use of the undocumented Core Graphics functions, so exercise your discretion.

This project relies heavily on work by Wade Tregaskis and his Rotating Windows.

© 2006 Ankur Kothari.