Syphon
List of all members
SyphonServer Class Reference

Inherits NSObject.

Instance Methods

Instantiation
(id) - initWithName:context:options:
 
Publishing Frames
(void) - publishFrameTexture:textureTarget:imageRegion:textureDimensions:flipped:
 
(BOOL) - bindToDrawFrameOfSize:
 
(void) - unbindAndPublish
 
(SyphonImage *) - newFrameImage
 
(void) - stop
 

Properties

Properties
CGLContextObj context
 
NSString * name
 
NSDictionary * serverDescription
 
BOOL hasClients
 

Related Functions

(Note that these are not member functions.)

Server Options Dictionary Key Constants
NSString *const SyphonServerOptionIsPrivate
 
NSString *const SyphonServerOptionAntialiasSampleCount
 
NSString *const SyphonServerOptionDepthBufferResolution
 
NSString *const SyphonServerOptionStencilBufferResolution
 

Method Documentation

◆ initWithName:context:options:()

- (id) initWithName: (NSString *)  serverName
context: (CGLContextObj)  context
options: (NSDictionary *)  options 

Creates a new server with the specified human-readable name (which need not be unique), CGLContext and options. The server will be started immediately. Init may fail and return nil if the server could not be started.

This method does not lock the CGL context. If there is a chance other threads may use the context during calls to this method, bracket it with calls to CGLLockContext() and CGLUnlockContext().

Parameters
serverNameNon-unique human readable server name. This is not required and may be nil, but is usually used by clients in their UI to aid identification.
contextThe CGLContextObj context that textures will be valid and available on for publishing.
optionsA dictionary containing key-value pairs to specify options for the server. Currently supported options are SyphonServerOptionIsPrivate, SyphonServerOptionAntialiasQuality and SyphonServerOptionHasDepthBuffer. See their descriptions for details.
Returns
A newly intialized SyphonServer. Nil on failure.

◆ publishFrameTexture:textureTarget:imageRegion:textureDimensions:flipped:()

- (void) publishFrameTexture: (GLuint)  texID
textureTarget: (GLenum)  target
imageRegion: (NSRect)  region
textureDimensions: (NSSize)  size
flipped: (BOOL)  isFlipped 

Publishes the part of the texture described in region of the named texture to clients. The texture is copied and can be safely disposed of or modified once this method has returned. You should not bracket calls to this method with calls to -bindToDrawFrameOfSize: and -unbindAndPublish - they are provided as an alternative to using this method.

This method does not lock the server's CGL context. If there is a chance of other threads using the context during calls to this method, bracket it with calls to CGLLockContext() and CGLUnlockContext(), passing in the value of the server's context property as the argument.

Parameters
texIDThe name of the texture to publish, which must be a texture valid in the CGL context provided when the server was created.
targetGL_TEXTURE_RECTANGLE_EXT or GL_TEXTURE_2D.
regionThe sub-region of the texture to publish.
sizeThe full size of the texture
isFlippedIs the texture flipped?

◆ bindToDrawFrameOfSize:()

- (BOOL) bindToDrawFrameOfSize: (NSSize)  size

Binds an FBO for you to publish a frame of the given dimensions by drawing into the server's context (check it using the context property). If YES is returned, you must pair this with a call to -unbindAndPublish once you have finished drawing. If NO is returned you should abandon drawing and not call -unbindAndPublish. This method does not lock the server's CGL context. If there is a chance other threads may use the context during calls to this method, bracket it with calls to CGLLockContext() and CGLUnlockContext(), passing in the value of the server's context property as the argument.

Parameters
sizeThe size the frame you wish to publish.
Returns
YES if binding succeeded, NO otherwise.

◆ unbindAndPublish()

- (void) unbindAndPublish

Restores any previously bound FBO and publishes the just-drawn frame. This method will flush the GL context (so you don't have to). This method does not lock the server's CGL context. If there is a chance of other threads using the context during calls to this method, bracket it with calls to CGLLockContext() and CGLUnlockContext(), passing in the value of the server's context property as the argument.

◆ newFrameImage()

- (SyphonImage *) newFrameImage

Returns a SyphonImage representing the current output from the server, valid in the server's CGL context. Call this method every time you wish to access the current server frame. This object has a limited useful lifetime, and may have GPU resources associated with it: you should release it as soon as you are finished drawing with it.

This method does not lock the CGL context. If there is a chance other threads may use the context during calls to this method, or while you are drawing with the returned SyphonImage, bracket access with calls to CGLLockContext() and CGLUnlockContext().

Returns
A SyphonImage representing the current output from the server. YOU ARE RESPONSIBLE FOR RELEASING THIS OBJECT when you are finished with it.

◆ stop()

- (void) stop

Stops the server instance. Use of this method is optional and releasing all references to the server has the same effect.

Friends And Related Function Documentation

◆ SyphonServerOptionIsPrivate

- (NSString* const) SyphonServerOptionIsPrivate
related

If this key is matched with a NSNumber with a BOOL value YES, then the server will be invisible to other Syphon users. You are then responsible for passing the NSDictionary returned by serverDescription to processes which require it to create a SyphonClient. Default is NO.

◆ SyphonServerOptionAntialiasSampleCount

- (NSString* const) SyphonServerOptionAntialiasSampleCount
related

If this key is matched with a NSNumber with a NSUInteger value greater than zero, the server will, when using the bindToDrawFrameOfSize / unbindAndPublish API, render to an antialiased render buffer with the requested multisample count (via the FBO MSAA and BLIT extensions). Default sample count is 0 should this key be ommited, indicating no antialiased buffers will be used. If the requested sample count is not supported by the GL context, the nearest supported sample count will be used instead. If MSAA is not supported at all, this key will be ignored and the server will render without the antialiasing stage.

◆ SyphonServerOptionDepthBufferResolution

- (NSString* const) SyphonServerOptionDepthBufferResolution
related

If this key is matched with a NSNumber with an integer value greater than zero, the server will render to an FBO with a depth buffer attached. The value provided should indicate the desired resolution of the buffer: 16, 24 or 32. The server will always attempt to attach a depth buffer when one is requested, however it may create one of a resolution other than that requested. This has useful effect only when using the bindToDrawFrameOfSize / unbindAndPublish API.

◆ SyphonServerOptionStencilBufferResolution

- (NSString* const) SyphonServerOptionStencilBufferResolution
related

If this key is matched with a NSNumber with an integer value greater than zero, the server will render to an FBO with a stencil buffer attached. The value provided should indicate the desired resolution of the buffer: 1, 4, 8 or 16. The server will always attempt to attach a stencil buffer when one is requested, however it may create one of a resolution other than that requested.

Property Documentation

◆ context

- (CGLContextObj) context
readatomicassign

The CGLContext the server uses for drawing. This may or may not be the context passed in at init.

◆ name

- (NSString*) name
readwriteatomicretain

A string representing the name of the SyphonServer.

◆ serverDescription

- (NSDictionary*) serverDescription
readatomicassign

A dictionary describing the server. Normally you won't need to access this, however if you created the server as private (using SyphonServerOptionIsPrivate) then you must pass this dictionary to any process in which you wish to create a SyphonClient. You should not rely on the presence of any particular keys in this dictionary. The content will always conform to the <NSCoding> protocol.

◆ hasClients

- (BOOL) hasClients
readatomicassign

YES if clients are currently attached, NO otherwise. If you generate frames frequently (for instance on a display-link timer), you may choose to test this and only call publishFrameTexture:textureTarget:imageRegion:textureDimensions:flipped: when clients are attached.