CGFunction Reference

Derived from
Framework
ApplicationServices/ApplicationServices.h
Companion guide
Declared in
CGFunction.h

Overview

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 by Task

Creating a CGFunction Object

Retaining and Releasing CGFunction Objects

Getting the CFType ID

Functions

CGFunctionCreate

Creates a Quartz function.

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] ≤ input[k] ≤ domain[2*k+1]. 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] ≤ output[k] ≤ range[2*k+1]. 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.

Availability
  • Available in iOS 2.0 and later.
Declared In
CGFunction.h

CGFunctionGetTypeID

Returns the type identifier for Quartz function objects.

CFTypeID CGFunctionGetTypeID (
   void
);
Return Value

The identifier for the opaque type CGFunctionRef.

Availability
  • Available in iOS 2.0 and later.
Declared In
CGFunction.h

CGFunctionRelease

Decrements the retain count of a function object.

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
CGFunction.h

CGFunctionRetain

Increments the retain count of a function object.

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
CGFunction.h

Callbacks

CGFunctionEvaluateCallback

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

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

If you name your function MyCGFunctionEvaluate, you would declare it like this:

void MyCGFunctionEvaluate (
   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];
}
Availability
  • Available in iOS 2.0 and later.
Declared In
CGFunction.h

CGFunctionReleaseInfoCallback

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

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

If you name your function MyCGFunctionReleaseInfo, you would declare it like this:

void MyCGFunctionReleaseInfo (
   void *info
);

Parameters
info

The info parameter passed to CGFunctionCreate.

Availability
  • Available in iOS 2.0 and later.
Declared In
CGFunction.h

Data Types

CGFunctionRef

An opaque type that represents a callback function.

typedef struct CGFunction *CGFunctionRef;
Availability
  • Available in iOS 2.0 and later.
Declared In
CGFunction.h

CGFunctionCallbacks

A structure that contains callbacks needed by a CGFunction object.

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 iOS 2.0 and later.
Declared In
CGFunction.h