/*****************************************************************************
*                                                                            *
*   IMFADE.SPL   Copyright (C) 2026 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Fades an image horizontally or vertically                   *
*                                                                            *
*   Revisions:   22 Jul 2026  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_IMFADE

    IMFADE

    Purpose: Fades an image horizontally or vertically by adjusting its alpha channel.

    Syntax:  IMFADE(image, percent, direction)

             image     - An array, the source image.

             percent   - Optional. A real from 0.0 to 1.0. The fraction
                         of the image to fade. Defaults to 1.0, fade
                         the entire image. 

             direction - Optional. An integer, the fade direction.

                          0: Left to right (default).
                          1: Right to left.
                          2: Botom to top.
                          3: Top to bottom.

    Returns: An image with the applied fade.

    Example:
             W1: readimage(gethome + "\data\mandrill.bmp")
             W2: imfade(w1)setaspectct(-1)
             W3: imfade(w1, 0.5, 1)setaspectct(-1)
             W4: imfade(w3, 0.5, 3)setaspectct(-1)

             W1 loads a color BMP image.

             W2 fades the entire image from the left.

             W3 fades 50% of the image from the right.

             W4 fades 50% of W3 from the top. The result is the original image
             faded both from the right and from the top.

    Remarks:
             IMFADE performs a linear fade by gradually reducing the alpha channel
             from fully opaque to transparent.

             The PERCENT parameter controls how far across (or down) IMAGE the
             fade extends.

    See Also:
             Getrgb
             Image24
             Linspace
             Rgbimage
#endif


/* fade image from left/top/right/bottom */
imfade(w = refwindow(w0), percent = 1, direction = 0)
{
        local acnt, r, g, b, a, f, h, nf, len, img;

        acnt = argc;

        if (isscalar(w))
        {
                direction = w;
                w = refwindow(w0);
                acnt = 0;
        }

        /* rgb and alpha components */
        (r, g, b, a) = getrgb(w);

        (nr, nc) = size(r);

        if (imhasalpha(w))
        {
                /* factor out existing transparency */
                r /= a;
                g /= a;
                b /= a;
        }

        /* transparency ramp */
        nf  = (direction > 1) ? nc : nr;
        len = castint(nf * percent);
        h   = linspace(0, 1, len);
        f   = ones(nf, 1);
        f[1..len] = h;

        /* update alpha matrix based on direction */
        if (direction > 1)
        {
                /* top or bottom */
                if (len > nc)
                {
                        len = nc;
                        f = extract(f, 1, len);
                }

                if (direction > 2)
                {
                        f = rev(f);
                }

                f = rep(f', nr);
        }
        else
        {
                /* right or left */
                if (len > nr)
                {
                        len = nr;
                        f = extract(f, 1, len);
                }

                if (direction > 0)
                {
                        f = rev(f);
                }

                f = repcol(f, nc);
        }

        /* new transparency mask */
        a *= f;

        /* premultiply transparency */
        img = rgbimage(r*a, g*a, b*a, a);

        /* attributes */
        img.xoffset = w.xoffset;
        img.yoffset = w.yoffset;

        if (acnt > 0)
        {
                return(img);
        }
        else
        {
                w0 = img;
        }
}