# 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.

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 will be invoked to send a notification that conversion has finished. Callback functions are invoked by interrupts from the DSP, so callbacks will 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.

## See Also

`DSP_LoadGraphics
DSP_UnloadGraphics
DSP_Scaling*
OS_DisableIrq
DSP_CALC_SCALING_SIZE_FX
DSP_CalcScalingFactor*
fx32`

## Revision History

2008/10/22 Added a note in line with internal changes to synchronous functions.
2008/09/06 Added information about the data transfer method.
2008/08/28 Initial version.

CONFIDENTIAL