kStatus GoSetup_SelectCustomEnhancedSurfaceFlatnessFilter	(	GoSetup	setup,
		GoRole	role,
		GoPreFilterLengthOption	length,
		const GoPreFilterCoefficient *	coefficientsArray
	)

Selects using a custom enhanced surface flatness filter, if device supports enhanced surface flatness filtering, where filter coefficients are provided by the user.

Check that the device supports it by calling GoSetup_IsEnhancedSurfaceFlatnessFilterSupported(). If enhanced surface flatness filtering is not supported an error code will be returned.

This API sets three things to ensure consistency between all three properties of the custom enhanced surface flatness filter:

• sets the mode to GO_PREFILTER_TYPE_CUSTOM,
• sets the length of the enhanced surface flatness filter,
• and sets the actual coefficients for the enhanced surface flatness filter.

The number of coefficients in the input array "coefficientsArray" MUST be equal to "length" parameter. This is the responsibility of the caller. The API cannot know if the input array is too small, resulting in accessing memory outside of the actual array, possibly leading to unpredictable behaviour.

Each coefficient value must be with the range of the minimum and maximum allowable values given by GoSetup_CoefficientMinValue() and GoSetup_CoefficientMaxValue(). The sum of all the coefficient values must be equal to GoSetup_CoefficientsExpectedSum().

NOTE: because of the inherent limitations of exactly representing a floating point number, the above comparisons to the limits cannot be exact.

Version

Introduced in firmware 6.3.1.83

Parameters

setup	GoSetup object.
role	Determines which device to retrieve the value from. Use GO_ROLE_MAIN or GOROLE_BUDDYIDX(buddyidx). See GoRole for more details.
length	The number of filter coefficients to use in the custom enhanced surface flatness filter.
coefficientsArray	An input array of enhanced surface flatness filter coefficients to use. Number of entries MUST be equal to length.

Returns

Operation status.