Syphon Framework

Developing with Syphon

Developing with Syphon

The Syphon framework provides the classes necessary to add Syphon support to your application. SyphonServer is used to make frames available to other applications. SyphonServerDirectory is used to discover available servers. SyphonClient is used to connect to and receive frames from a SyphonServer.

The framework requires MacOS X 10.6 or later. Syphon makes use of IOSurface, which is a 10.6-only technology. Syphon takes advantage of other 10.6 features such as blocks, and is compatible with garbage-collection.

To include Syphon in your application, follow these steps:

  1. Add the framework to your Xcode project.

    The simplest way is to drag it to the Frameworks group in the project window.

  2. Link your application with Syphon at build time.

    Add the framework to the Link Binary With Libraries build phase of your application's target.

  3. Copy the framework into your application's bundle.

    Add a new Copy Files build phase to your application's target.
    Select Frameworks as the destination.
    Drag the Syphon framework into the build phase.

  4. Import the headers.

    #import <Syphon/Syphon.h> in any file where you want to use Syphon classes.

Servers

Class documentation: SyphonServer

Create a server:

 SyphonServer *myServer = [[SyphonServer alloc] initWithName:@"My Output" context:myContext options:nil];

and then publish new frames (you can also use GL_TEXTURE_2D textures):

 [myServer publishFrameTexture:myTex textureTarget:GL_TEXTURE_RECTANGLE_EXT imageRegion:NSMakeRect(0, 0, width, height) textureDimensions:NSMakeSize(width, height) flipped:NO];

Alternatively there are methods to bind and unbind the server to the OpenGL context, so you can draw into it directly. You can publish new frames as often as you like, but if you only publish when you have a frame different from the previous one, then clients can do less work. You must stop the server when you are finished with it:

 [myServer stop];

Finding Servers

Class documentation: SyphonServerDirectory

SyphonServerDirectory handles server discovery for you. You can get an array of dictionaries describing available servers:

 NSArray *available = [[SyphonServerDirectory sharedDirectory] servers];

The servers property can be observed for changes, or you can register to receive the notifications posted by SyphonServerDirectory.

Server description dictionaries are used by Syphon when you create a client, and also contain information you can use to describe available servers in your UI:

 [myMenuItem setTitle:[description objectForKey:SyphonServerDescriptionNameKey]];

Clients

Class documentation: SyphonClient, SyphonImage

Usually you create a client with a server description dictionary you obtained from SyphonServerDirectory:

 SyphonClient *myClient = [[SyphonClient alloc] initWithServerDescription:description options:nil newFrameHandler:^(SyphonClient *client) {
        [myView setNeedsDisplay:YES];
 }];

The new-frame handler is optional: you can pass in nil. Here we use it to tell a view it needs to draw whenever the client receives a frame.

When you are ready to draw:

 SyphonImage *myFrame = [myClient newFrameImageForContext:cgl_ctx];
 if (myFrame)
 {
        GLuint tex = myFrame.textureName;
        NSSize dimensions = myFrame.textureSize;

        // YOUR OPENGL DRAWING CODE HERE

        [myFrame release];
 }

As with servers, you must stop the client when you are finished with it:

 [myClient stop];

Syphon.framework in a Plugin

If you are using Syphon in any sort of plugin, please download the framework source and compile a version of the framework with unique class names. This avoids class-name conflicts if another plugin or the host application also embeds the Syphon framework. The framework source is set up to make this easy for you: you just need to change one build setting.

  1. Open the framework's Xcode project.

  2. Define SYPHON_UNIQUE_CLASS_NAME_PREFIX using the Preprocessor Macros build setting.

    Select the Syphon target in the project window.
    Click the Build Settings tab to display the build settings.
    Scroll down (or use the search field) to find the Preprocessor Macros (GCC_PREPROCESSOR_DEFINITIONS) setting.
    Double click the setting to add SYPHON_UNIQUE_CLASS_NAME_PREFIX=MyPluginName as a macro.

  3. Build the framework.

    The built framework will have custom class names. The headers alias the custom names, so you can use SyphonServer, SyphonClient, SyphonImage and SyphonServerDirectory as normal in your code.

More examples and help

Example projects implementing a server and client are included with the Syphon SDK. You can also examine the source to the provided Syphon implementations at their Google Code project.

Use the Syphon developer forum to ask questions, and for any development related discussion.

Good luck!

Framework development

If you'd like to examine the framework's source code, report a bug, or get involved in development, head on over to the Syphon framework Google Code project.

 All Classes Functions Variables Properties