PgDrawGradient()

Ask the graphics driver to render a gradient

Synopsis:

int PgDrawGradient( PhPoint *ul,
                    PhPoint *lr,
                    unsigned long gradient_type,
                    unsigned long transition_type, 
                    unsigned long num_color_pts,
                    PgColor_t color1, 
                    PgColor_t color2,
                    PgColor_t color3,
                    PgColor_t color4,
                    unsigned long table_size,
                    unsigned char *transition_table );

Library:

ph

Description:

This function requests the graphics driver to render a gradient. The arguments are:

ul

A pointer to the upper left corner of the rendering rectangle.

lr

A pointer to the lower right corner of the rendering rectangle.

gradient_type

The type of gradient:

• Pg_GRAD_HORIZONTAL
• Pg_GRAD_VERTICAL
• Pg_GRAD_DIAGF -- forward diagonal.
• Pg_GRAD_DIAGB -- backward diagonal.
• Pg_GRAD_4POINT -- four-point gradient (Pg_GRAD_DIAGF and Pg_GRAD_DIAGB mixed together).
• Pg_GRAD_BOX_DIAGF -- boxy forward diagonal.
• Pg_GRAD_BOX_DIAGB -- boxy backward diagonal.
• Pg_GRAD_BOX_4POINT -- boxy four-point.

Boxy Gradients are similar to the nonboxy gradients, but are rendered using rectangles instead of horizontal lines while scaling the gradient information to the rendered rectangle. As a result, it takes less time to render boxy gradients. They don't look as precise as the nonboxy versions, but look cool anyway. ;-)

transition_type

One of the following:

• Pg_GRAD_LINEAR -- the color of the isochrome lines changes linearly from the starting color to the end color.
• Pg_GRAD_HILL -- the color of the isochrome lines changes from the starting color to the end color and back to the starting color again. The end color is reached in the middle isochrome line.
• Pg_GRAD_HILL2 -- similar to Pg_GRAD_HILL, except there are two transitions from the starting color to the end color.
• Pg_GRAD_EXP -- the color of the isochrome lines changes exponentially from the starting color to the end color.
• Pg_GRAD_TABLE -- the transition from the starting color to the end color is controlled by the transition_table and table_size arguments.

num_color_pts

The resolution of the gradient. Basically it's the number of colors you want to have the driver calculate between the endpoint colors.

color1

The first color endpoint.

color2

The second color endpoint.

color3

The third color endpoint (only used in four-point gradients).

color4

The fourth color endpoint (only used in four-point gradients).

table_size

The size of the user-defined transition table. This needs to be set only if the transition type is Pg_GRAD_TABLE.

transition_table

A pointer to the user-defined transition table. This needs to be set only if the transition type is Pg_GRAD_TABLE.

Returns:

0

Success.

-1

An error occurred.

Examples:

// Draw a basic horizontal gradient from blue to red,
// with 20 colors in a rectangle of size 100 x 200

PhRect_t GradRect={{0,0},{100,200}};

PgDrawGradient(&GradRect.ul,&GradRect.lr,Pg_GRAD_HORIZONTAL,
    Pg_GRAD_LINEAR,20,Pg_RED,Pg_BLUE,0,0,0,NULL);

Classification:

Photon

See also:

PgCalcColorContrast(), PgColor_t

"Gradients" in the Raw Drawing and Animation chapter of the Photon Programmer's Guide