Scale Video Filter
[Video Filters]

---

Detailed Description

The video scale (resize) filter implements a high quality bicubic scaler to change the dimensions of the video.

Filter Parameters:

  Name                                |   Type   | Opt/Reqd |    Range
  =======================================================================================
  FE2_SCALE_WIDTH                     | Numeric  | Optional | [-3,)
  FE2_SCALE_HEIGHT                    | Numeric  | Optional | [-3,)

Example Usage:

  sc = Flix2_AddFilter(&filter, flix, FE2_FILTER_SCALE);
  // scale to 320xXXX maintaining the display aspect ratio
  // e.g., 640x480 -> 320x240 (4:3)
  //       640x360 -> 320x180 (16:9)
  if(sc == ON2_OK)
      sc = Flix2_FilterSetParam(filter, FE2_SCALE_WIDTH, 320);
  if (sc == ON2_OK)
      sc = Flix2_FilterSetParam(filter, FE2_SCALE_HEIGHT, -2);

Reserved values

As of v8.0.9.0, the following values have special meaning and are applicable to both FE2_SCALE_WIDTH and FE2_SCALE_HEIGHT:

• 0: display dimension
• -1: original dimension (default)
• -2: calculate dimension based on its complement and the display aspect ratio
• -3: calculate dimension based on its complement and the original aspect ratio

Display aspect ratio is calculated based on the desired resolution, as set by the container, e.g., the input is encoded at 4:3, but displays at 16:9. Needless to say, this is clip dependent and requires the correct values be set within the container and forwarded from the input source.

Attention:

Only one dimension may be set to [-2,-3]. The other MUST be > -2.

Deprecated functions
on2sc	video_options_GetImageHeight (const FLIX2HANDLE flix, int32_t *lpImageHeight)
	Get the current scaled image height.
on2sc	video_options_SetImageHeight (FLIX2HANDLE flix, const int32_t lImageHeight)
	Set the scaled image height.
on2sc	video_options_GetImageWidth (const FLIX2HANDLE flix, int32_t *lpImageWidth)
	Get the current scaled image width.
on2sc	video_options_SetImageWidth (FLIX2HANDLE flix, const int32_t lImageWidth)
	Set the scaled image width.
on2sc	video_options_GetUseSourceDimensions (const FLIX2HANDLE flix, on2bool *bpUseSourceDimensions)
	Determine if the source's dimensions will be used instead of the scaled dimensions.
on2sc	video_options_SetUseSourceDimensions (FLIX2HANDLE flix, const on2bool bUseSourceDimensions)
	Switch between source and scaled dimensions.
Defines
#define	FE2_FILTER_SCALE
	Filter name for use with Flix2_AddFilter().
#define	FE2_SCALE_WIDTH
	Filter parameter name for scaled width.
#define	FE2_SCALE_HEIGHT
	Filter parameter name for scaled height.

---

Define Documentation

#define FE2_FILTER_SCALE

Filter name for use with Flix2_AddFilter().

Definition at line 70 of file scale.h.

#define FE2_SCALE_HEIGHT

Filter parameter name for scaled height.

Use FE2_SCALE_HEIGHT with Flix2_FilterSetParam() and Flix2_FilterGetParam() to set and/or get the scaled height of the video.

Note:

The value returned by a call to Flix2_FilterGetParam() when this name is specified should only be considered valid if it follows a call to Flix2_FilterSetParam().

Attention:

This function can NOT be used to obtain information about the unscaled input video, use video_options_GetSourceHeight().

See also:

Reserved values

Definition at line 100 of file scale.h.

#define FE2_SCALE_WIDTH

Filter parameter name for scaled width.

Use FE2_SCALE_WIDTH with Flix2_FilterSetParam() and Flix2_FilterGetParam() to set and/or get the scaled width of the video.

Note:

The value returned by a call to Flix2_FilterGetParam() when this name is specified should only be considered valid if it follows a call to Flix2_FilterSetParam().

Attention:

This function can NOT be used to obtain information about the unscaled input video, use video_options_GetSourceWidth().

See also:

Reserved values

Definition at line 85 of file scale.h.

---

Function Documentation

on2sc video_options_GetImageHeight	(	const FLIX2HANDLE	flix,
		int32_t *	lpImageHeight
	)

Get the current scaled image height.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[out]	lpImageHeight	Image height (in pixels)

Return values:

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

Note:

This value should only be considered valid if it follows a call to video_options_SetImageHeight(). It can not be used to get information about the unscaled input video.

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

Deprecated:

Please use:

• Flix2_AddFilter()
• Flix2_FilterGetParam()
• Flix2_FilterSetParam()

With the constants:

• FE2_FILTER_SCALE
• FE2_SCALE_WIDTH
• FE2_SCALE_HEIGHT

for access to the flix engine video scaling filter.

on2sc video_options_GetImageWidth	(	const FLIX2HANDLE	flix,
		int32_t *	lpImageWidth
	)

Get the current scaled image width.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[out]	lpImageWidth	Image width (in pixels)

Return values:

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

Note:

This value should only be considered valid if it follows a call to video_options_SetImageWidth(). It can not be used to get information about the unscaled input video.

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

Deprecated:

Please use:

• Flix2_AddFilter()
• Flix2_FilterGetParam()
• Flix2_FilterSetParam()

With the constants:

• FE2_FILTER_SCALE
• FE2_SCALE_WIDTH
• FE2_SCALE_HEIGHT

for access to the flix engine video scaling filter.

on2sc video_options_GetUseSourceDimensions	(	const FLIX2HANDLE	flix,
		on2bool *	bpUseSourceDimensions
	)

Determine if the source's dimensions will be used instead of the scaled dimensions.

Parameters:

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

Return values:

	ON2_OK	The dimension 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:

The flix engine encodes video using the video source dimensions by default. If FE2_FILTER_SCALE has not been added to the filter chain, video will be encoded using source dimensions.

on2sc video_options_SetImageHeight	(	FLIX2HANDLE	flix,
		const int32_t	lImageHeight
	)

Set the scaled image height.

Determines the scaled height of the output video.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[in]	lImageHeight	Image height (in pixels)

Return values:

	ON2_OK	The image height 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:

The default is to use the source's height.

Deprecated:

Please use:

• Flix2_AddFilter()
• Flix2_FilterGetParam()
• Flix2_FilterSetParam()

With the constants:

• FE2_FILTER_SCALE
• FE2_SCALE_WIDTH
• FE2_SCALE_HEIGHT

for access to the flix engine video scaling filter.

on2sc video_options_SetImageWidth	(	FLIX2HANDLE	flix,
		const int32_t	lImageWidth
	)

Set the scaled image width.

Determines the scaled width of the output video.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[in]	lImageWidth	Image width (in pixels)

Return values:

	ON2_OK	The image width 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:

The default is to use the source's width.

Deprecated:

Please use:

• Flix2_AddFilter()
• Flix2_FilterGetParam()
• Flix2_FilterSetParam()

With the constants:

• FE2_FILTER_SCALE
• FE2_SCALE_WIDTH
• FE2_SCALE_HEIGHT

for access to the flix engine video scaling filter.

on2sc video_options_SetUseSourceDimensions	(	FLIX2HANDLE	flix,
		const on2bool	bUseSourceDimensions
	)

Switch between source and scaled dimensions.

Parameters:

[in]	flix	Handle to the Flix Engine returned from Flix2_Create() or Flix2_CreateEx()
[in]	bUseSourceDimensions	New dimension status. on2true to use source dimensions, on2false to use scaled dimensions.

Return values:

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

Note:

By default, the source dimensions will be used, unless a call to video_options_SetImageHeight() or video_options_SetImageWidth() has been made.

Deprecated:

The flix engine encodes video using the video source dimensions by default. If FE2_FILTER_SCALE has not been added to the filter chain, video will be encoded using source dimensions.

Attention:

Use of this function will cause FE2_FILTER_SCALE settings to be ignored. If FE2_FILTER_SCALE has been added to the filter chain via the Filter Interface this function is unnecessary. Scaling can be disabled by calling Flix2_RemoveFilter() with the handle returned from Flix2_AddFilter().

---