- Qt 6.12
- Qt Canvas Painter
- C++ Classes
- QCanvasGradient
- Qt Canvas Painter | Commercial or GPLv3

# QCanvasGradient Class

QCanvasGradient is the base class for all QCanvasPainter gradient brushes. More...

Header: | `#include <QCanvasGradient>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)` `target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter)`
Since: | Qt 6.11
Inherited By: | QCanvasBoxGradient, QCanvasConicalGradient, QCanvasLinearGradient, and QCanvasRadialGradient

- List of all members, including inherited members

## Public Functions

| QCanvasGradient()
| QCanvasGradient(const QCanvasGradient &)
| QCanvasGradient(QCanvasGradient &&)
`(since 6.12)` void | addColorStop(float position, const QColor &color)
QColor | endColor() const
void | setColorAt(float position, const QColor &color)
void | setEndColor(const QColor &color)
`(since 6.12)` void | setImage(const QCanvasImage &image, int index = 0)
void | setStartColor(const QColor &color)
void | setStops(const QCanvasGradientStops &stops)
QColor | startColor() const
QCanvasGradientStops | stops() const
QCanvasBrush::BrushType | type() const
| operator QCanvasBrush() const
| operator QVariant() const
QCanvasGradient & | operator=(QCanvasGradient &&)
QCanvasGradient & | operator=(const QCanvasGradient &)

## Protected Functions

| ~QCanvasGradient()

## Related Non-Members

| QCanvasGradientStops
bool | operator!=(const QCanvasGradient &lhs, const QCanvasGradient &rhs)
QDataStream & | operator<<(QDataStream &stream, const QCanvasGradient &gradient)
QDataStream & | operator<<(QDataStream &stream, const QCanvasGradientStop &stop)
bool | operator==(const QCanvasGradient &lhs, const QCanvasGradient &rhs)
QDataStream & | operator>>(QDataStream &stream, QCanvasGradient &gradient)
QDataStream & | operator>>(QDataStream &stream, QCanvasGradientStop &stop)

## Detailed Description

QCanvasGradient is the base class for all QCanvasPainter gradient brushes. Currently there are four type of gradients: QCanvasLinearGradient, QCanvasRadialGradient, QCanvasConicalGradient and QCanvasBoxGradient.

If no stops are provided with setStartColor, setEndColor, setColorAt or setStops, the gragient is rendered as start color white (255,255,255) and end color transparent (0,0,0,0). If only a single stop is provided, the gradient is filled with this color.

QCanvasPainter uses two different approaches for painting gradients.

- With maximum of 2 stops, the colors are passed into shader as 2 vec4 uniforms. This makes animating 2 stop gradients very performant, with no extra steps in between.
- With more than 2 stops, the colors are passed into shader as a one dimensional texture. By default the texture size is 1x256 pixels, optimized for quality and performance. The textures are cached, so when gradient stops or colors don't change, previous texture can be reused even when other gradient properties (like position, angle etc.) change. Although animating multi-stop gradients is fast, it will cause texture uploads, so consider if it is worth it.

There are few environment variables to control the gradients texture usage:

- QCPAINTER_DISABLE_TEXTURE_USAGE_TRACKING - By default, gradient texture usage is tracked and kept under the max amount. Set this environment variable to disable the tracking and keep all gradient textures in memory.
- QCPAINTER_MAX_TEXTURES - By default, the maximum amount of textures is `1024`. Set this environt variable to contain number of desired maximum texture amount. The currently unused temporary gradient textures are automatically removed when the maximum amount is reached.

  Note: This does not have an effect when the texture usage tracking has been disabled.

## Member Function Documentation

### `[constexpr noexcept default]` QCanvasGradient::QCanvasGradient()

Default-constructs an instance of QCanvasGradient.

### `[noexcept default]` QCanvasGradient::QCanvasGradient(const QCanvasGradient &)

Copy-constructs an instance of QCanvasGradient.

### `[noexcept default]` QCanvasGradient::QCanvasGradient(QCanvasGradient &&)

Move-constructs an instance of QCanvasGradient.

### `[noexcept protected default]` QCanvasGradient::~QCanvasGradient()

Destroys the instance of QCanvasGradient.

### `[since 6.12]` void QCanvasGradient::addColorStop(float position, const QColor &color)

Creates a stop point at the given position with the given color. The given position must be in the range 0 to 1.

This method is provided for HTML CanvasGradient compatibility. It is equivalent to setColorAt().

This function was introduced in Qt 6.12.

See also setStops() and stops().

### QColor QCanvasGradient::endColor() const

Returns the gradient end color or the color at the largest position. If the end color has not been set, returns the default end color transparent black (0, 0, 0, 0).

See also setEndColor().

### void QCanvasGradient::setColorAt(float position, const QColor &color)

Creates a stop point at the given position with the given color. The given position must be in the range 0 to 1.

See also setStops() and stops().

### void QCanvasGradient::setEndColor(const QColor &color)

Sets the end color of gradient to color. This is equal to calling setColorAt() with position `1`.

See also endColor().

### `[since 6.12]` void QCanvasGradient::setImage(const QCanvasImage &image, int index = 0)

Uses the image as the gradient source at the y-coordinate index. This is an alternative for setting the gradient stops using e.g. setStops() or setColorAt(). The expected default width of the image is 256 pixels, but it can be adjusted by defining the QCPAINTER_GRADIENT_SIZE. Index parameter is optional and not needed when the height of the image is 1 pixel. The maximum value of index should be image height - 1.

Possible reasons to use this method instead of setting stops:

- Slightly faster to create as stops don't need to be parsed. Also, multiple gradients can be included in a single image using index.
- The ability to use gradient from design / image directly, instead of converting it to set of stops.
- The ability to have non-linear gradients, like e.g. Gaussian curve.

Note: If both the stops and the image have been set, stops will be used.

Here is a simple example of how to use a `256x1` gradient image:

     static QImage image(":/gradient1.png");
     QCanvasImage gradImage = p->addImage(image);
     QRectF rect(0, 0, 200, 200);
     QCanvasRadialGradient rg(rect.center(), 150, 20);
     rg.setImage(gradImage);
     p->setFillStyle(rg);
     p->fillRect(rect);

This function was introduced in Qt 6.12.

See also setStops().

### void QCanvasGradient::setStartColor(const QColor &color)

Sets the start color of gradient to color. This is equal to calling setColorAt() with position `0`.

See also startColor().

### void QCanvasGradient::setStops(const QCanvasGradientStops &stops)

Replaces the current set of stop points with the given stops.

The rules for the stops list are following:

- The list should contain at least 2 stops.
- The positions of the stops must be in the range 0 to 1, and must be sorted with the lowest stops first.
- The first position must be at 0.0 and the last position at 1.0.

See also setColorAt() and stops().

### QColor QCanvasGradient::startColor() const

Returns the gradient start color or the color at the smallest position. If the start color has not been set, returns the default start color white (255, 255, 255).

See also setStartColor().

### QCanvasGradientStops QCanvasGradient::stops() const

Returns the stop points for this gradient.

See also setStops() and setColorAt().

### QCanvasBrush::BrushType QCanvasGradient::type() const

Returns the type of gradient.

### QCanvasGradient::operator QCanvasBrush() const

Returns the gradient as a QCanvasBrush.

### QCanvasGradient::operator QVariant() const

Returns the gradient as a QVariant.

### `[noexcept default]` QCanvasGradient &QCanvasGradient::operator=(QCanvasGradient &&)

Move-assigns other to this QCanvasGradient instance.

### `[noexcept default]` QCanvasGradient &QCanvasGradient::operator=(const QCanvasGradient &)

Copy-assigns other to this QCanvasGradient instance.

## Related Non-Members

### QCanvasGradientStops

Typedef for QList<QCanvasGradientStop>.

### `[noexcept]` bool operator!=(const QCanvasGradient &lhs, const QCanvasGradient &rhs)

Returns `true` if the gradient lhs is different from rhs; `false` otherwise.

See also operator==().

### QDataStream &operator<<(QDataStream &stream, const QCanvasGradient &gradient)

Writes the given gradient to the given stream and returns a reference to the stream.

See also Serializing Qt Data Types.

### QDataStream &operator<<(QDataStream &stream, const QCanvasGradientStop &stop)

Writes gradient stop to the given stream and returns a reference to the stream.

See also Serializing Qt Data Types.

### `[noexcept]` bool operator==(const QCanvasGradient &lhs, const QCanvasGradient &rhs)

Returns `true` if the gradient lhs is equal to rhs; `false` otherwise.

See also operator!=().

### QDataStream &operator>>(QDataStream &stream, QCanvasGradient &gradient)

Reads the given gradient from the given stream and returns a reference to the stream.

See also Serializing Qt Data Types.

### QDataStream &operator>>(QDataStream &stream, QCanvasGradientStop &stop)

Reads a gradient stop from the given stream and returns a reference to the stream.

See also Serializing Qt Data Types.