A few new features and general stability improvements, but mostly a very thorough cleanup of the source code, so you can actually compile it now.

Compilation Instructions

Open Xcode preferences, scroll across to Source Trees and add one with a Setting Name of “QSFrameworks” and path of /Applications/Quicksilver.app/Contents/Frameworks/.

Then unzip Quicksilver.xcodeproj.zip, and open the Quicksilver.xcodeproj project in Xcode. Make sure you set the Active Build Configuration to “Release”. Click the Build button and you’re away.

Note: This build appears to be incompatible with the File Tagging plugin.

Bug fixes

A lot of features were buried in the source, available only by setting some preferences to allow them. Mostly it was due to buggy implementation or pending improvements. I managed to resurrect a few of these nifty ones and fix a few old bugs that have annoyed me for ages.

Color handling

Color handling was commented out in the Quicksilver source; probably because it resulted in errors. A simple change in the source allowed correct handling of color values, and the code for drawing the icon was already there. I added functionality to allow dropping colors from the Quicksilver object pane into color wells and the like - which is what makes this useful.

Uninstalled plugins

Added a plugin set to the plugins preference pane to list plugins that you haven’t yet installed or downloaded. Not sure why this was commented out; I didn’t have to add any new code here.

Triggers

There was a very annoying bug in the triggers preference pane that haunted me from the day I started using Quicksilver. Switching to the iTunes trigger set resulted in errors, and often froze or messed up Quicksilver. Finally, it’s fixed, and we can see and use these triggers.

Speaking of plugins; I think I heard mention of a “plugin check bug” fixed somewhere, but it wasn’t working for me so I’ve also fixed the issue where the plugin list would be blank until you hit refresh.

Miscellaneous bug fixes

Other things like crashing when you try to relaunch with the “Customize” preference pane open, and with the source, hundreds of warnings when trying to compile, errors in the shell scripts when working in a path with non-alphanumeric characters, etc. have also been fixed.

Tidy up

[I wonder] how long it’ll take people to notice the Frankensteinian nature of the source and respond - appropriately - with pitchforks. Alcor

I’ll have to agree with Alcor - to say the source is a mess would be an understatement. There are hundreds of compiler warnings, unused or unimplemented features, classes, objects, code, structures, nibs, etc. Hundreds. I’ve tried to remove as much of the redundant or test code as possible and I’ve yet to reach the end. Mind you, I’ve been doing this for hours a day for the past week. The formatting and indentation is almost as bad. I’m cleaning that up too, with some good old regular expressions and elbow grease. As I go, I’m also trying to improve the logic where I see potential for improvement. Already the application is feeling more responsive but I want to also reduce the memory footprint.

Why go to all this trouble? Mainly, to

• Make the source more readable; make it easier for people to understand what’s going on.
• Improve the performance of the application in both speed and memory usage.
• Fix existing bugs and add new features.

In the meantime, I’ll continue my clean up of the Quicksilver source and when it’s lookin’ fine perhaps post it up (the QS license doesn’t really say much about the source, so I might have to ask Alcor first. Perhaps he’d like to add it to the subversion repository after reviewing?).

Lastly, let me just say, I’ve learnt a lot from looking at the source code to Quicksilver. There are some very neat tricks in there, and great little snippets that could be very useful elsewhere. So thank you Mr. Jitkoff; thank you for writing the application, and thank you for the releasing the source code. It is highly appreciated.

One thing I disagree with, though, is the excessive use of the “do shell script” AppleScript. I like the “Run Command in Shell” action just fine. But if you want an icon, writing an Obj-C wrapper isn’t too much work. Especially since you have this source code.

I’ve also got a bit more on Quicksilver coming up shortly.

The GetCurrentEventKeyModifiers() call works on Mac OS X v10.2 and later through which one can check for shiftKey, cmdKey, optionKey and controlKey.

I use the something like the following to check if the shift key is pressed during launch for my compression app.

#import <Cocoa/Cocoa.h>
#import <Carbon/Carbon.h>

int main(int argc, char *argv[]) {
    NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
    if((GetCurrentEventKeyModifiers() & shiftKey)!=0) {
        // Change something useful
        NSLog(@"Shift key pressed during launch");
    }
    [[NSApplication sharedApplication] run];
    [pool release];
    return 0;
}

In the highly unlikely event that you’ve just got a call to NSApplicationMain in your main function (joking), you can just test (GetCurrentEventKeyModifiers() & shiftKey)!=0 in the -applicationWillFinishLaunching: method in your NSApplication delegate.

Any new APIs in Leopard to achieve this or any easier way?

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.

The framework (in more ways than one) for our smoking window is the Smoke framework embedded inside the Disco app. In your Xcode project, you can reference the framework straight from within the application. You’ll have to press Cmd-Shift-G and type in the path as you can’t navigate into bundles using the standard open file dialog. Normally the location is “/Applications/Disco.app/Frameworks/” inside which is the Smoke.framework bundle which we’re interested in.

Alternatively, you can copy the framework to /Library/Frameworks/ and reference it from there. If you need to modify the framework (more on that later) it’s best to choose this option so you leave the contents of the Disco application alone.

Head to the headers

Before we can use the framework, we need to have a valid header or header files for the framework, which tell Xcode (and us) mainly about the classes and methods in Smoke.framework. The headers aren’t included in the framework anymore, but to generate a header file is a simple matter of using a utility like class-dump on the framework.

Download Smoke.h:

You can take a look inside the header and see a bit of what’s possible with the framework. When you’re ready, we’ll move onto the…

Setup

Now we’ve got the framework and header in place, we need to code to actually get a window to smoke. On the surface, this is astonishingly simple.

In your Xcode project, make sure you’ve added Smoke.framework and Smoke.h as well as Quartz.framework as the smoke needs to use this. Now create a new Objective-C subclass. In this example we’ve used an NSWindow subclass, but you could just as easily subclass NSObject and only apply smoke on selected outlets. If you really wanted to start a bonfire, you could add a category to NSWindow just for smoking!

Firstly, we define everything in our header file. Our class is called SmokingWindow (SmokeWindow is taken by Smoke.framework) and we have four methods.

The header file will look something like this:

//
//  SmokingWindow.h
//  Smoke
//
//  Created by Ankur Kothari on 13/04/07.
//  Copyright 2007 Vacuous Virtuoso. All rights reserved.
//

#import <Cocoa/Cocoa.h>
#import <Quartz/Quartz.h>
#import "Smoke.h"

@interface SmokingWindow : NSWindow {
    SmokeController *theSmokeController;
    int smoking;
}
-(int)smoking;
-(IBAction)startSmoking:(id)sender;
-(IBAction)stopSmoking:(id)sender;
-(IBAction)toggleSmoke:(id)sender;
@end

• -smoking returns whether (1) or not (0) the window is currently smoking. It’s not needed to smoke, but it’s good practice.
• -startSmoking obviously starts the window smoking, and
• -stopSmoking stop the window smoking
• -toggleSmoke will stop the window smoking if it is, or start it smoking if it isn’t.

We’re storing the current state of the window for use by the -smoking method in the int smoking, and theSmokeController is a pointer to a SmokeController which will be doing most of the work.

Ok, now to the implementation.

//
//  SmokingWindow.m
//  Smoke
//
//  Created by Ankur Kothari on 13/04/07.
//  Copyright 2007 Vacuous Virtuoso. All rights reserved.
//

#import "SmokingWindow.h"


@implementation SmokingWindow

-(void)awakeFromNib
{
    SmokeCapabilities *smokeCapabilities = [SmokeCapabilities sharedCapabilities];
    theSmokeController = [[SmokeController alloc] init];
    [theSmokeController doExpensiveThreadedInitializations];
    [theSmokeController setSmokeAlgorithm:[smokeCapabilities smokeAlgorithm]];
    [theSmokeController attachToWindow:self];
    smoking = 0;
    [theSmokeController showWindow:self];
}

-(IBAction)toggleSmoke:(id)sender{
    if(smoking){
        [self stopSmoking:sender];
    } else {
        [self startSmoking:sender];
    }
}

-(IBAction)startSmoking:(id)sender
{
    if(!smoking){
        [theSmokeController startSmoking:self];
        smoking = 1;
    }
}

-(IBAction)stopSmoking:(id)sender
{
    if(smoking){
        [theSmokeController stopSmoking:self];
        smoking = 0;
    }
}

-(int)smoking{
    return smoking;
}
@end

The first few lines in -awakeFormNib get the SmokeController do some initialization.

SmokeCapabilities *smokeCapabilities = [SmokeCapabilities sharedCapabilities];
theSmokeController = [[SmokeController alloc] init];
[theSmokeController doExpensiveThreadedInitializations];
[theSmokeController setSmokeAlgorithm:[smokeCapabilities smokeAlgorithm]];

To tell the SmokeController which window to ‘burn’, the -attachToWindow: method is used. Since we’re using an NSWindow subclass in this example, we can just set it to self, otherwise you’ll need a pointer or outlet to an instance of NSWindow.

[theSmokeController attachToWindow:self];

To just make extra sure that the position of the smoke wont be offset if the window is dragged around during initialization, we call the -showWindow method. This isn’t completely necessary.

[theSmokeController showWindow:self];

To heat or cool the window, theSmokeController responds to -startSmoking and -stopSmoking. Easy enough!

More fun!

For extra smoking fun, you can add bindings to your application to control many aspects of the smoke. You can adjust the initial temperature, the amount of pressure exerted by the mouse, the FPS, and many more. Just check the UserDefaults.plist file located in the Resources folder in Smoke.framework.¹

Hacking the smoke framework

To get even more out of the smoke framework, you can edit various files within the framework itself. Most of the files are in the “Resources” folder. One of the most useful ones to edit is called boundary.cikernal. In the first two lines you can specify the height and width of the OpenGL view that the smoke appears in.

Enjoy the smoke!

Sample project

Developments

Austin has also graciously agreed to let me develop Fumo, the smoking Quicksilver interface.

Although there is still some talk about the HIG, usability, eye candy and so on, the controversy phase is mostly over. Speaking of which, you can call me what you like, but I think the HIG is definitely not dead. Outdated perhaps, but there needs to be a standard. There are many aspects to the existing HIG that developers need to follow in order to make the Mac experience enjoyable. I’ll talk about this in detail later. My rant about the HIG.

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.

If you’re like me, one of the first things you do when you see a cool app is dig straight into the resources folder. Well, right-clicking on Disco.app and hitting “Show package contents” is pretty revealing. Charge straight into the Contents folder, and you’ll see a nice little folder bearing the name “Frameworks”. Need I say any more? Just like all you need for Core Graphics is contained within my Core Graphics Framework, so the smoking windows code is contained in this little folder. It’s a simple matter of doing a class-dump to build some headers (or if you got in early, the headers are already there), and you have access to all the smoke you need. So, are you interested? Download the Disco beta and drag it to your applications folder. Then, you may proceed to grab a copy of my (modified) version of the smoking windows project and play around with it at your leisure! I quote from Toxic Software:

If your hardware is capable enough you should be able to see the smoke effect rising from the top of the window. (It might take 10 to 20 seconds for the smoke to appear). You can change the smoke parameters by using the smoke settings window (dialog? pane? view?) within Disco. Then just copy Disco’s prefs (com.discoapp.Disco.plist) to SecondHandSmoke’s prefs (com.example.SecondHandSmoke.plist).

Obviously, this way of setting preferences isn’t very flash, so you can just set the specific preference keys from within your code, and it’ll still run fine. Don’t expect that done from me, though, I’ve got a lot of work to catch up on. Then again, if someone wants to make their window smoke and can’t get their head around the preferences, I can always take a little break and help you out.

Second Hand Smoke

Have fun, and try not to get addicted to smoking.

Update: This smoke no longer works with the version 1.0 release of Disco. Updated smoking instructions here.