vImagePiecewiseRational_PlanarF(_:_:_:_:_:_:_:_:_:)

Declaration

func vImagePiecewiseRational_PlanarF(_ src: UnsafePointer<vImage_Buffer>, _ dest: UnsafePointer<vImage_Buffer>, _ topCoefficients: UnsafeMutablePointer<UnsafePointer<Float>?>, _ bottomCoefficients: UnsafeMutablePointer<UnsafePointer<Float>?>, _ boundaries: UnsafePointer<Float>, _ topOrder: UInt32, _ bottomOrder: UInt32, _ log2segments: UInt32, _ flags: vImage_Flags) -> vImage_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, and rowBytes 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 memory

topCoefficients

An array of pointers to polynomial coefficient arrays The array of pointers has length 2^log2segments. Each array pointed to has length topOrder+1.

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 2^log2segments. Each array pointed to has length bottomOrder+1.

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 (2^log2segments)+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

Discussion

This function is similar to vImagePiecewisePolynomial_PlanarF(_:_:_:_:_:_:_:) 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.