# DSP_ScalingFx*

## Syntax

    BOOL DSP_ScalingFxAsyncEx(
            const void* src,
            void* dst,
            u16 img_width,
            u16 img_height,
            fx32 rx,
            fx32 ry,
            DSPGraphicsScalingMode mode,
            u16 x,
            u16 y,
            u16 width,
            u16 height,
            DSP_GraphicsCallback callback
        );

    BOOL DSP_ScalingFx(src, dst, img_width, img_height, rx, ry, mode);
    BOOL DSP_ScalingFxEx(src, dst, img_width, img_height, rx, ry, mode, x, y, width, height);
    BOOL DSP_ScalingFxAsync(src, dst, img_width, img_height, rx, ry, mode, callback);

## Arguments

`src` | Buffer in main memory that holds the data to convert.
`dst` | Buffer in main memory that will hold the converted data. You must allocate a buffer large enough to store the converted data.
`img_width` | Width of the image to convert.
`img_height` | Height of the image to convert.
`rx` | Horizontal scaling factor. This is valid between 31 and 0.001. Decimals will be truncated to three decimal places.
`ry` | Vertical scaling factor. This is valid between 31 and 0.001. Decimals will be truncated to three decimal places.
`mode` | Interpolation method for scaling up (expanding) or scaling down (shrinking). Specifies the `DSPGraphicsScalingMode` (described below).
`x` | X-coordinate of the region to process, with the coordinate system origin (0,0) located at the upper-left of `src`.
`y` | Y-coordinate of the region to process, with the coordinate system origin (0,0) located at the upper-left of `src`.
`width` | Width of the region to process.
`height` | Height of the region to process.
`callback` | Callback function when processing ends.

## Return Values

Returns `TRUE` when processing ends normally.
Returns `FALSE` when conversion did not end normally or the graphics component is already processing something.

## Description

Uses the DSP to expand or shrink image data.

The addresses indicated by `src` and `dst` must be 4-byte aligned.

Data is transferred between main memory and the DSP (WRAM-C) using the AHB. Data transfers between main memory and the DSP run at a lower priority than DMA data transfers, so AHB arbitration causes delays if another process uses frequent DMA transfers while scaling is being processed.

Factors are specified as fixed-point numbers (`fx32`). Due to underflow that can occur during decimal calculations, the converted size may differ from the intended value. However, you can use the `DSP_CALC_SCALING_SIZE_FX` macro to get the converted size that results from the `DSP_ScalingFx*` functions. We have provided a function, `DSP_CalcScalingFactorFx32`, that takes the converted size as an argument and can get the factors to pass to this function.

Note that there are restrictions in this function for values that can be specified as arguments because of design issues of the internal processes. For more information, see Note, below.

The interpolation method used while processing is defined by `DSPGraphicsScalingMode` as follows.

    typedef DSPWord DSPGraphicsScalingMode;
    #define DSP_GRAPHICS_SCALING_MODE_N_NEIGHBOR (DSPGraphicsScalingMode)0x0001
    #define DSP_GRAPHICS_SCALING_MODE_BILINEAR   (DSPGraphicsScalingMode)0x0002
    #define DSP_GRAPHICS_SCALING_MODE_BICUBIC    (DSPGraphicsScalingMode)0x0003

Starting from the top, these represent nearest-neighbor, bilinear, and bicubic interpolation. As a basic rule, processing time increases as you move down the list.

When the asynchronous versions of this function (`*Async`) are run, the callback function registered as an argument is invoked to send a notification that conversion has finished. Callback functions are invoked by interrupts from the DSP, so callbacks never return if interrupts have been prohibited by a function such as `OS_DisableIrq`. Do not disable DSP interrupts from another process while asynchronous versions of this function are running.

With the `*Ex` versions of this function, you can specify an arbitrary region of the source image and process only that region.

## Note

In the synchronous version, the `OS_Sleep` function waits for the process to complete. Therefore, call the `OS_InitThread`, `OS_InitTick`, and `OS_InitAlarm` functions beforehand.

Be careful because when the following conditions are met with this function, the internal DSP process does not end. If the conditions are met `SDK_ASSERTMSG` is called.

- When the post-process data size is larger than the size of the original data

  mode | Condition
  `DSP_GRAPHICS_SCALING_MODE_N_NEIGHBOR DSP_GRAPHICS_SCALING_MODE_BILINEAR` | (Width of output data) (vertical scaling factor) >=8192
  `DSP_GRAPHICS_SCALING_MODE_BICUBIC` | (Width of output data) (vertical scaling factor) >=4096

- When the post-process data size is smaller than the size of the original data

  mode | Condition
  `DSP_GRAPHICS_SCALING_MODE_N_NEIGHBOR DSP_GRAPHICS_SCALING_MODE_BILINEAR` | (Width of input data) >=8192
  `DSP_GRAPHICS_SCALING_MODE_BICUBIC` | (Width of input data) >=4096

## See Also

`DSP_LoadGraphics`
`DSP_UnloadGraphics`
`DSP_Scaling*`
`OS_DisableIrq`
`DSP_CALC_SCALING_SIZE_FX`
`DSP_CalcScalingFactor*`
`fx32`

## Revision History

2009/04/03 Added descriptions about the restrictions related to arguments in Note.
2008/10/22 Added a note about changes in the synchronous function.
2008/09/06 Added information about data transfer methods.
2008/08/28 Initial version.

CONFIDENTIAL