PgDrawGradient(), PgDrawGradientCx()

Ask the graphics driver to render a gradient

Synopsis:

int PgDrawGradient( PhPoint_t *ul,
                    PhPoint_t *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 );

int PgDrawGradientCx( void *dc,
                      PhPoint_t *ul,
                      PhPoint_t *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 );

Arguments:

dc

PgDrawGradientCx() only. A void pointer to any type of draw context. Examples of draw contexts are:

• a PhDrawContext_t returned by PhDCCreate()
• a PmMemoryContext_t returned by PmMemCreateMC()
• a PpPrintContext_t returned by PpCreatePC()
• a PdOffscreenContext_t returned by PdCreateOffscreenContext()

---

If the target offscreen context or device is of type Pg_IMAGE_PALETTE_BYTE, a filled rectangle will be drawn instead of a gradient.

---

ul, lr

Pointers to PhPoint_t structures that define the upper left and lower right corners 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, color2, color3, color4

PgColor_t values that define the color endpoints.

The color3 and color4 arguments are used only 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.

Library:

ph

Description:

These functions request the graphics driver to render a gradient. PgDrawGradient() works on the current draw context, while you can specify the draw context for PgDrawGradientCx().

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, PhPoint_t

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