Brightness/Contrast/Hue/Saturation Video Filter
[Video Filters]

---

Detailed Description

The BCHS video filter is a filter used to modify the brightness, contrast, hue and/or saturation of the source image.

Filter Parameters:

   Name                                |   Type   | Opt/Reqd |    Range
   =======================================================================================
   FE2_BCHS_BRIGHTNESS                 | Numeric  | Optional | [-255,255]
   FE2_BCHS_CONTRAST                   | Numeric  | Optional | [-255,255]
   FE2_BCHS_HUE                        | Numeric  | Optional | [-180,180]
   FE2_BCHS_SATURATION                 | Numeric  | Optional | [-255,255]

Example Usage:

   sc = Flix2_AddFilter(&filter, flix, FE2_FILTER_BCHS);
   //up the contrast by ~10%
   if(sc == ON2_OK)
       sc = Flix2_FilterSetParamAsStr(filter, FE2_BCHS_CONTRAST, 25.5);

Deprecated functions
on2sc	editor_options_GetBrightness (const FLIX2HANDLE flix, int32_t *pBrightness)
	Get the current brightness adjustment factor.
on2sc	editor_options_SetBrightness (FLIX2HANDLE flix, const int32_t brightness)
	Set the brightness adjustment factor.
on2sc	editor_options_GetUseBrightness (const FLIX2HANDLE flix, on2bool *pUseBrightness)
	Determine if the brightness filter is enabled.
on2sc	editor_options_SetUseBrightness (FLIX2HANDLE flix, const on2bool bUseBrightness)
	Enable/disable the brightness filter.
on2sc	editor_options_GetContrast (const FLIX2HANDLE flix, double *pContrast)
	Get the current contrast adjustment factor.
on2sc	editor_options_SetContrast (FLIX2HANDLE flix, const double contrast)
	Set the contrast adjustment factor.
on2sc	editor_options_GetUseContrast (const FLIX2HANDLE flix, on2bool *pUseContrast)
	Determine if the contrast filter is enabled.
on2sc	editor_options_SetUseContrast (FLIX2HANDLE flix, const on2bool bUseContrast)
	Enable/disable the contrast filter.
on2sc	editor_options_GetHue (const FLIX2HANDLE flix, int32_t *pHue)
	Get the current hue adjustment factor.
on2sc	editor_options_SetHue (FLIX2HANDLE flix, const int32_t hue)
	Set the hue adjustment factor.
on2sc	editor_options_GetUseHue (const FLIX2HANDLE flix, on2bool *pUseHue)
	Determine if the hue filter is enabled.
on2sc	editor_options_SetUseHue (FLIX2HANDLE flix, const on2bool bUseHue)
	Enable/disable the hue filter.
on2sc	editor_options_GetSaturation (const FLIX2HANDLE flix, double *pSaturation)
	Get the current saturation adjustment factor.
on2sc	editor_options_SetSaturation (FLIX2HANDLE flix, const double saturation)
	Set the saturation adjustment factor.
on2sc	editor_options_GetUseSaturation (const FLIX2HANDLE flix, on2bool *pUseSaturation)
	Determine if the saturation filter is enabled.
on2sc	editor_options_SetUseSaturation (FLIX2HANDLE flix, const on2bool bUseSaturation)
	Enable/disable the saturation filter.
Defines
#define	FE2_FILTER_BCHS
	Filter name for use with Flix2_AddFilter().
#define	FE2_BCHS_BRIGHTNESS
	Parameter for the brightness adjustment factor.
#define	FE2_BCHS_CONTRAST
	Parameter for the contrast adjustment factor.
#define	FE2_BCHS_HUE
	Parameter for the hue adjustment factor.
#define	FE2_BCHS_SATURATION
	Parameter for the saturation adjustment factor.

---

Define Documentation

#define FE2_BCHS_BRIGHTNESS

Parameter for the brightness adjustment factor.

Determines the level by which to adjust the brightness. Brightness is adjusted on a scale of -255 to 255, with 0 indicating no change. To increase the relative brightness of the video, use a positive number. To decrease the relative brightness of the video, use a negative number.

Note:

Valid range: [-255,255]
Default: 0 (no change)

Definition at line 58 of file bchs.h.

#define FE2_BCHS_CONTRAST

Parameter for the contrast adjustment factor.

Determines the level by which to adjust the contrast. Contrast is adjusted on a scale of -255 to 255, with 0 indicating no change. To increase the relative contrast of the video, use a positive number. To decrease the relative contrast of the video, use a negative number.

Note:

Valid range: [-255,255]
Default: 0 (no change)

Definition at line 69 of file bchs.h.

#define FE2_BCHS_HUE

Parameter for the hue adjustment factor.

Determines the level by which to adjust the hue. Hue is adjusted on a scale of -180 to 180, with 0 indicating no change. To adjust the hue of the video towards red, use a negative number. To adjust the hue of the video towards green, use a positive number.

Note:

Valid range: [-180,180]
Default: 0 (no change)

Definition at line 79 of file bchs.h.

#define FE2_BCHS_SATURATION

Parameter for the saturation adjustment factor.

Determines the level by which to adjust the saturation. Saturation is adjusted on a scale of -255 to 255, with 0 indicating no change. To increase the relative saturation of the video, use a positive number. To decrease the relative saturation of the video, use a negative number.

Note:

Valid range: [-255,255] Default: 0

Definition at line 90 of file bchs.h.

#define FE2_FILTER_BCHS

Filter name for use with Flix2_AddFilter().

Definition at line 47 of file bchs.h.

---

Function Documentation

on2sc editor_options_GetBrightness	(	const FLIX2HANDLE	flix,
		int32_t *	pBrightness
	)

Get the current brightness adjustment factor.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[out]	pBrightness	Brightness factor (-255..255)

Return values:

	ON2_OK	The brightness value was successfully retrieved from the engine.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

If a value other than ON2_OK is returned, the output variables should not be considered valid.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_BRIGHTNESS parameter. This function will be removed in a future release.

on2sc editor_options_GetContrast	(	const FLIX2HANDLE	flix,
		double *	pContrast
	)

Get the current contrast adjustment factor.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[out]	pContrast	Contrast factor (-255..255)

Return values:

	ON2_OK	The contrast value was successfully retrieved from the engine.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

If a value other than ON2_OK is returned, the output variables should not be considered valid.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_CONTRAST parameter. This function will be removed in a future release.

on2sc editor_options_GetHue	(	const FLIX2HANDLE	flix,
		int32_t *	pHue
	)

Get the current hue adjustment factor.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[out]	pHue	Hue factor (-180..180)

Return values:

	ON2_OK	The hue value was successfully retrieved from the engine.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

If a value other than ON2_OK is returned, the output variables should not be considered valid.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_HUE parameter. This function will be removed in a future release.

on2sc editor_options_GetSaturation	(	const FLIX2HANDLE	flix,
		double *	pSaturation
	)

Get the current saturation adjustment factor.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[out]	pSaturation	Saturation factor (-255..255)

Return values:

	ON2_OK	The saturation value was successfully retrieved from the engine.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

If a value other than ON2_OK is returned, the output variables should not be considered valid.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_SATURATION parameter. This function will be removed in a future release.

on2sc editor_options_GetUseBrightness	(	const FLIX2HANDLE	flix,
		on2bool *	pUseBrightness
	)

Determine if the brightness filter is enabled.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[out]	pUseBrightness	Variable to update with the current brightness enable status

Return values:

	ON2_OK	The brightness filter enable status was successfully retrieved from the engine.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

If a value other than ON2_OK is returned, the output variables should not be considered valid.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_BRIGHTNESS parameter. This function will be removed in a future release.

on2sc editor_options_GetUseContrast	(	const FLIX2HANDLE	flix,
		on2bool *	pUseContrast
	)

Determine if the contrast filter is enabled.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[out]	pUseContrast	Variable to update with the current contrast enable status

Return values:

	ON2_OK	The contrast filter enable status was successfully retrieved from the engine.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

If a value other than ON2_OK is returned, the output variables should not be considered valid.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_CONTRAST parameter. This function will be removed in a future release.

on2sc editor_options_GetUseHue	(	const FLIX2HANDLE	flix,
		on2bool *	pUseHue
	)

Determine if the hue filter is enabled.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[out]	pUseHue	Variable to update with the current hue enable status

Return values:

	ON2_OK	The hue filter enable status was successfully retrieved from the engine.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

If a value other than ON2_OK is returned, the output variables should not be considered valid.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_HUE parameter. This function will be removed in a future release.

on2sc editor_options_GetUseSaturation	(	const FLIX2HANDLE	flix,
		on2bool *	pUseSaturation
	)

Determine if the saturation filter is enabled.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[out]	pUseSaturation	Variable to update with the current saturation enable status

Return values:

	ON2_OK	The saturation filter enable status was successfully retrieved from the engine.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

If a value other than ON2_OK is returned, the output variables should not be considered valid.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_SATURATION parameter. This function will be removed in a future release.

on2sc editor_options_SetBrightness	(	FLIX2HANDLE	flix,
		const int32_t	brightness
	)

Set the brightness adjustment factor.

Determines the level by which to adjust the brightness. Brightness is adjusted on a scale of -255 to 255, with 0 indicating no change. To increase the relative brightness of the video, use a positive number. To decrease the relative brightness of the video, use a negative number.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[in]	brightness	Brightness Factor (-255 to 255)

Return values:

	ON2_OK	The brightness value was successfully set in the engine.
	ON2_INVALID_PARAMS	The value is out of range.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

This call will have no effect on the encoded video unless the brightness filter is enabled with editor_options_SetUseBrightness(). The default value is 0 (no change).

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_BRIGHTNESS parameter. This function will be removed in a future release.

on2sc editor_options_SetContrast	(	FLIX2HANDLE	flix,
		const double	contrast
	)

Set the contrast adjustment factor.

Determines the level by which to adjust the contrast. Contrast is adjusted on a scale of -255 to 255, with 0 indicating no change. To increase the relative contrast of the video, use a positive number. To decrease the relative contrast of the video, use a negative number.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[in]	contrast	Contrast Factor (-255 to 255)

Return values:

	ON2_OK	The contrast value was successfully set in the engine.
	ON2_INVALID_PARAMS	The value is out of range.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

This call will have no effect on the encoded video unless the contrast filter is enabled with editor_options_SetUseContrast(). The default value is 1.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_CONTRAST parameter. This function will be removed in a future release.

on2sc editor_options_SetHue	(	FLIX2HANDLE	flix,
		const int32_t	hue
	)

Set the hue adjustment factor.

Determines the level by which to adjust the hue. Hue is adjusted on a scale of -180 to 180, with 0 indicating no change. To adjust the hue of the video towards red, use a negative number. To adjust the hue of the video towards green, use a positive number.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[in]	hue	Hue Factor (-180 to 180)

Return values:

	ON2_OK	The hue value was successfully set in the engine.
	ON2_INVALID_PARAMS	The value is out of range.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

This call will have no effect on the encoded video unless the hue filter is enabled with editor_options_SetUseHue(). The default value is 0.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_HUE parameter. This function will be removed in a future release.

on2sc editor_options_SetSaturation	(	FLIX2HANDLE	flix,
		const double	saturation
	)

Set the saturation adjustment factor.

Determines the level by which to adjust the saturation. Saturation is adjusted on a scale of -255 to 255, with 0 indicating no change. To increase the relative saturation of the video, use a positive number. To decrease the relative saturation of the video, use a negative number.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[in]	saturation	Saturation Factor (-255 to 255)

Return values:

	ON2_OK	The saturation value was successfully set in the engine.
	ON2_INVALID_PARAMS	The value is out of range.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

This call will have no effect on the encoded video unless the saturation filter is enabled with editor_options_SetUseSaturation(). The default value is 1.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_SATURATION parameter. This function will be removed in a future release.

on2sc editor_options_SetUseBrightness	(	FLIX2HANDLE	flix,
		const on2bool	bUseBrightness
	)

Enable/disable the brightness filter.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[in]	bUseBrightness	New brightness enable status. on2true to enable, on2false to disable.

Return values:

	ON2_OK	The brightness enable status was successfully set in the engine.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

By default, the brightness filter is disabled.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_BRIGHTNESS parameter. This function will be removed in a future release.

on2sc editor_options_SetUseContrast	(	FLIX2HANDLE	flix,
		const on2bool	bUseContrast
	)

Enable/disable the contrast filter.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[in]	bUseContrast	New contrast enable status. on2true to enable, on2false to disable.

Return values:

	ON2_OK	The contrast enable status was successfully set in the engine.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

By default, the contrast filter is disabled.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_CONTRAST parameter. This function will be removed in a future release.

on2sc editor_options_SetUseHue	(	FLIX2HANDLE	flix,
		const on2bool	bUseHue
	)

Enable/disable the hue filter.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[in]	bUseHue	New hue enable status. on2true to enable, on2false to disable.

Return values:

	ON2_OK	The hue enable status was successfully set in the engine.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

By default, the hue filter is disabled.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_HUE parameter. This function will be removed in a future release.

on2sc editor_options_SetUseSaturation	(	FLIX2HANDLE	flix,
		const on2bool	bUseSaturation
	)

Enable/disable the saturation filter.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[in]	bUseSaturation	New saturation enable status. on2true to enable, on2false to disable.

Return values:

	ON2_OK	The saturation enable status was successfully set in the engine.
	ON2_NET_ERROR	The underlying communication layer failed.

Note:

By default, the saturation filter is disabled.

Deprecated:

Use the Filter Interface along with FE2_FILTER_BCHS and the FE2_BCHS_SATURATION parameter. This function will be removed in a future release.

---