Mac Developer Library

Developer

ApplicationServices Framework Reference CGFunction Reference

Options
Deployment Target:

On This Page
Language:

CGFunction Reference

The CGFunctionRef opaque type provides a general facility for defining and using callback functions. These functions can take an arbitrary number of floating-point input values and pass back an arbitrary number of floating-point output values.

Quartz uses CGFunction objects to implement shadings. CGShading Reference describes the parameters and semantics required for the callbacks used by CGFunction objects.

Functions

  • Creates a Quartz function.

    Declaration

    Swift

    func CGFunctionCreate(_ info: UnsafeMutablePointer<Void>, _ domainDimension: UInt, _ domain: UnsafePointer<CGFloat>, _ rangeDimension: UInt, _ range: UnsafePointer<CGFloat>, _ callbacks: UnsafePointer<CGFunctionCallbacks>) -> CGFunction!

    Objective-C

    CGFunctionRef CGFunctionCreate ( void *info, size_t domainDimension, const CGFloat *domain, size_t rangeDimension, const CGFloat *range, const CGFunctionCallbacks *callbacks );

    Parameters

    info

    A pointer to user-defined storage for data that you want to pass to your callbacks. You need to make sure that the data persists for as long as it’s needed, which can be beyond the scope in which the Quartz function is used.

    domainDimension

    The number of inputs.

    domain

    An array of (2*domainDimension) floats used to specify the valid intervals of input values. For each k from 0 to (domainDimension - 1), domain[2*k] must be less than or equal to domain[2*k+1], and the kth input value will be clipped to lie in the interval domain[2*k] . If this parameter is NULL, then the input values are not clipped.

    rangeDimension

    The number of outputs.

    range

    An array of (2*rangeDimension) floats that specifies the valid intervals of output values. For each k from 0 to (rangeDimension - 1), range[2*k] must be less than or equal to range[2*k+1], and the kth output value will be clipped to lie in the interval range[2*k] . If this parameter is NULL, then the output values are not clipped.

    callbacks

    A pointer to a callback function table. This table should contain pointers to the callbacks you provide to implement the semantics of this Quartz function. Quartz makes a copy of your table, so, for example, you could safely pass in a pointer to a structure on the stack.

    Return Value

    The new Quartz function. You are responsible for releasing this object using CGFunctionRelease.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.2 and later.

  • Decrements the retain count of a function object.

    Declaration

    Objective-C

    void CGFunctionRelease ( CGFunctionRef function );

    Parameters

    function

    The function object to release.

    Discussion

    This function is equivalent to CFRelease, except that it does not cause an error if the function parameter is NULL.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.2 and later.

  • Increments the retain count of a function object.

    Declaration

    Objective-C

    CGFunctionRef CGFunctionRetain ( CGFunctionRef function );

    Parameters

    function

    The same function object you passed in as the function parameter.

    Return Value

    Discussion

    This function is equivalent to CFRetain, except that it does not cause an error if the function parameter is NULL.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.2 and later.

  • Returns the type identifier for Quartz function objects.

    Declaration

    Swift

    func CGFunctionGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CGFunctionGetTypeID ( void );

    Return Value

    The identifier for the opaque type CGFunctionRef.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.2 and later.

Callbacks

  • Performs custom operations on the supplied input data to produce output data.

    Declaration

    Swift

    typealias CGFunctionEvaluateCallback = CFunctionPointer<((UnsafeMutablePointer<Void>, UnsafePointer<CGFloat>, UnsafeMutablePointer<CGFloat>) -> Void)>

    Objective-C

    typedef void (*CGFunctionEvaluateCallback) ( void *info, const float *inData, float *outData );

    Parameters

    info

    The info parameter passed to CGFunctionCreate.

    inData

    An array of floats. The size of the array is that specified by the domainDimension parameter passed to the CGFunctionCreate function.

    outData

    An array of floats. The size of the array is that specified by the rangeDimension parameter passed to the CGFunctionCreate function.

    Discussion

    The callback you write is responsible for implementing the calculation of output values from the supplied input values. For example, if you want to implement a simple "squaring" function of one input argument to one output argument, your evaluation function might be:

    • void evaluateSquare(void *info, const float *inData, float *outData)
    • {
    • outData[0] = inData[0] * inData[0];
    • }

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

  • Performs custom clean-up tasks when Quartz deallocates a CGFunction object.

    Declaration

    Swift

    typealias CGFunctionReleaseInfoCallback = CFunctionPointer<((UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void (*CGFunctionReleaseInfoCallback) ( void *info );

    Parameters

    info

    The info parameter passed to CGFunctionCreate.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.2 and later.

Data Types

  • An opaque type that represents a callback function.

    Declaration

    Swift

    typealias CGFunctionRef = CGFunction

    Objective-C

    typedef struct CGFunction *CGFunctionRef;

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.2 and later.

  • A structure that contains callbacks needed by a CGFunction object.

    Declaration

    Swift

    struct CGFunctionCallbacks { var version: UInt32 var evaluate: CGFunctionEvaluateCallback var releaseInfo: CGFunctionReleaseInfoCallback }

    Objective-C

    struct CGFunctionCallbacks { unsigned int version; CGFunctionEvaluateCallback evaluate; CGFunctionReleaseInfoCallback releaseInfo }; typedef struct CGFunctionCallbacks CGFunctionCallbacks;

    Fields

    version

    The structure version number. For this structure, the version should be 0.

    evaluate

    The callback that evaluates the function.

    releaseInfo

    If non-NULL, the callback used to release the info parameter passed to CGFunctionCreate.

    Availability

    Available in OS X v10.2 and later.