# DSP_Scaling*

## Syntax

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

    BOOL DSP_Scaling(src, dst, img_width, img_height, rx, ry, mode);
    BOOL DSP_ScalingEx(src, dst, img_width, img_height, rx, ry, mode, x, y, width, height);
    BOOL DSP_ScalingAsync(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.

This function uses the AHB to transfer data between main memory and the DSP (WRAM-C). 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.

The scaling is specified by a floating-point number (`f32`) that is converted internally to a fixed-point number and calculated. Due to loss of precision during floating-point calculations, the post-conversion size may differ from the intended value. However, you can use the `DSP_CALC_SCALING_SIZE` macro to calculate the post-conversion size that will result from the `DSP_Scaling*` functions. We have also provided `DSP_CalcScalingFactor32`, a function that takes the post-conversion size as an argument and gets the scaling 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 is invoked to send a notification that conversion has finished. Callback functions are invoked by interrupts from the DSP. If interrupts have been prohibited by a function such as `OS_DisableIrq`, completion notifications from the DSP will be missed and callbacks will not be called. 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_CalcScalingFactor*
DSP_CALC_SCALING_SIZE
DSP_LoadGraphics
DSP_ScalingFx*
DSP_UnloadGraphics
OS_DisableIrq`

## Revision History

2008/10/22 Added a note about changes inside the synchronous function.
2008/09/06 Added information on data transfer methods.
2008/08/28 Added information to Description on a function that calculates factors. Also added links and descriptions of the `fx32` version.
2008/08/19 Described how prohibiting DSP interrupts affects asynchronous versions.
2008/05/22 Initial version.

CONFIDENTIAL