Applies a piecewise rational expression to an image in PlanarF format.
SDKs
- iOS 5.0+
- macOS 10.4+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
Framework
- Accelerate
Declaration
func vImagePiecewiseRational_PlanarF(_ src: Unsafe Pointer<v Image _Buffer>, _ dest: Unsafe Pointer<v Image _Buffer>, _ topCoefficients: Unsafe Mutable Pointer<Unsafe Pointer<Float>?>, _ bottomCoefficients: Unsafe Mutable Pointer<Unsafe Pointer<Float>?>, _ boundaries: Unsafe Pointer<Float>, _ topOrder: UInt32, _ bottomOrder: UInt32, _ log2segments: UInt32, _ flags: v Image _Flags) -> v Image _Error
Parameters
src
A pointer to a vImage buffer structure that contains the source image.
dest
A pointer to a vImage buffer data structure. You're responsible for filling out the
height
,width
, androw
fields of this structure, and for allocating a data buffer of the appropriate size. On return, the data buffer this structure points to contains the destination image data. When you no longer need the data buffer, you must deallocate the memoryBytes topCoefficients
An array of pointers to polynomial coefficient arrays The array of pointers has length 2log2segments. Each array pointed to has length
top
+1.Order Each polynomial coefficient array contains the coefficients for one polynomial. Note that a polynomial of order R has R+1 coefficients. All the polynomial coefficient arrays must be the same size, R+1, and in each array the coefficients must be ordered from the 0th-order term to the highest-order term.
bottomCoefficients
An array of pointers to polynomial coefficient arrays The array of pointers has length 2log2segments. Each array pointed to has length
bottom
+1.Order Each polynomial coefficient array contains the coefficients for one polynomial. Note that a polynomial of order R has R+1 coefficients. All the polynomial coefficient arrays must be the same size, R+1, and in each array the coefficients must be ordered from the 0th-order term to the highest-order term. These do not need to be the same order as the top polynomials.
boundaries
An array of floating-point values with size (2log2segments)+1, in increasing order, for separating adjacent ranges of pixel values. The first boundary value is the lowest in the range; input values lower than this are clipped to this value. The last boundary value is the highest in the range; input values higher than this are clipped to this value. The boundary values between the first and last separate the subranges from each other. The boundaries must be the same for both the top and bottom polynomials.
topOrder
The order of the top polynomial. Make sure you pass the order (that is, the highest power of x), not the number of coefiicients.
bottomOrder
The order of the bottom polynomial. Make sure you pass the order (that is, the highest power of x), not the number of coefiicients.
log2segments
The number of rationals represented as a base-2 logarithm. If you pass a non-integer power-of-two number of rational (for example, 5), you must round up to the next integer power of 2 (for the example of 5, that would be 8), and simply repeat the last rational the appropriate number of times.
flags
Reserved for future use; pass 0.
Return Value
kv
; otherwise, one of the error codes described in Data Types and Constants.
Discussion
This function is similar to v
except that it evaluates a piecewise rational expression in the form of:

Each polynomial has its own set of coefficients and its own polynomial order. The two polynomials share the same set of segment boundaries. If the polynomials are split then all the top polynomials must be of the same order, and all the bottom polynomials must be of the same order. However, regardless of whether the polynomial is split or not, the top polynomials do not need to be the same order as the bottom polynomials.
This function does not deliver IEEE-754 correct division. The divide does not round per the IEEE-754 current rounding mode. It incurs up to 2 ULPs (Units in the Last Place) of error. Edge cases involving denormals, infinities, NaNs and division by zero return undefined results. (They will not crash, but NaN is a likely result in such cases.) Denormals can be rescued on AltiVec enabled machines by turning off the Non-Java bit in the VSCR, at the expense of taking a many-thousand cycle kernel exception every time a denormal number is encountered. Since you can predict ahead of time whether a given set of bounded polynomials is going to encounter these conditions, this problem should be avoidable by wise choice of polynomials. Developers who require IEEE-754 correct results should call the polynomial evaluator above twice and do the division themselves.
The approximate cost of evaluating a rational (in the same units as polynomial above) is:
time = (base cost to touch all the data) + top polynomial order
+ bottom polynomial order + 4 + 4 * log2segments
With data not in cache, the time may be significantly different. For sufficiently small polynomials, the cost may be a fixed cost, dependent only on how much data is touched, and not on polynomial order.
This performance behavior is provided to help you evaluate speed tradeoffs. It is not a guaranteed. It is subject to change in future operating system revisions, and may be different on different hardware within the same or different operating system revisions.