- Qt 6.9
- Qt Quick
- QML Types
- QtQuick.Particles
- ImageParticle
- Qt 6.9.2 Reference Documentation

# ImageParticle QML Type

For visualizing logical particles using an image. More...

Import Statement: | `import QtQuick.Particles`
Inherits: | ParticlePainter

- List of all members, including inherited members

## Properties

- alpha : real
- alphaVariation : real
- autoRotation : bool
- blueVariation : real
- color : color
- colorTable : url
- colorVariation : real
- entryEffect : EntryEffect
- greenVariation : real
- opacityTable : url
- redVariation : real
- rotation : real
- rotationVariation : real
- rotationVelocity : real
- rotationVelocityVariation : real
- sizeTable : url
- source : url
- sprites : list<Sprite>
- spritesInterpolate : bool
- status : Status
- xVector : StochasticDirection
- yVector : StochasticDirection

## Detailed Description

This element renders a logical particle as an image. The image can be

- colorized
- rotated
- deformed
- a sprite-based animation

ImageParticles implictly share data on particles if multiple ImageParticles are painting the same logical particle group. This is broken down along the four capabilities listed above. So if one ImageParticle defines data for rendering the particles in one of those capabilities, and the other does not, then both will draw the particles the same in that aspect automatically. This is primarily useful when there is some random variation on the particle which is supposed to stay with it when switching painters. If both ImageParticles define how they should appear for that aspect, they diverge and each appears as it is defined.

This sharing of data happens behind the scenes based off of whether properties were implicitly or explicitly set. One drawback of the current implementation is that it is only possible to reset the capabilities as a whole. So if you explicitly set an attribute affecting color, such as redVariation, and then reset it (by setting redVariation to undefined), all color data will be reset and it will begin to have an implicit value of any shared color from other ImageParticles.

Note: The maximum number of image particles is limited to 16383.

## Property Documentation

alpha : real

An alpha to be applied to the image. This value is multiplied by the value in the image, and the value in the color property.

Particles have additive blending, so lower alpha on single particles leads to stronger effects when multiple particles overlap.

Alpha is measured from 0.0 to 1.0.

Default is 1.0

alphaVariation : real

The variation in the alpha channel between particles.

Alpha is measured from 0.0 to 1.0.

Default is 0.0

autoRotation : bool

If set to true then a rotation will be applied on top of the particles rotation, so that it faces the direction of travel. So to face away from the direction of travel, set autoRotation to true and rotation to 180.

Default is false

blueVariation : real

The variation in the blue color channel between particles.

Color is measured, per channel, from 0.0 to 1.0.

Default is 0.0

color : color

If a color is specified, the provided image will be colorized with it.

Default is white (no change).

colorTable : url

An image whose color will be used as a 1D texture to determine color over life. E.g. when the particle is halfway through its lifetime, it will have the color specified halfway across the image.

This color is blended with the color property and the color of the source image.

colorVariation : real

This number represents the color variation applied to individual particles. Setting colorVariation is the same as setting redVariation, greenVariation, and blueVariation to the same number.

Each channel can vary between particle by up to colorVariation from its usual color.

Color is measured, per channel, from 0.0 to 1.0.

Default is 0.0

entryEffect : EntryEffect

This property provides basic and cheap entrance and exit effects for the particles. For fine-grained control, see sizeTable and opacityTable.

Acceptable values are

Constant | Description
--- | ---
`ImageParticle.None` | Particles just appear and disappear.
`ImageParticle.Fade` | Particles fade in from 0 opacity at the start of their life, and fade out to 0 at the end.
`ImageParticle.Scale` | Particles scale in from 0 size at the start of their life, and scale back to 0 at the end.

The default value is `ImageParticle.Fade`.

greenVariation : real

The variation in the green color channel between particles.

Color is measured, per channel, from 0.0 to 1.0.

Default is 0.0

opacityTable : url

An image whose opacity will be used as a 1D texture to determine size over life.

This property is expected to be removed shortly, in favor of custom easing curves to determine opacity over life.

redVariation : real

The variation in the red color channel between particles.

Color is measured, per channel, from 0.0 to 1.0.

Default is 0.0

rotation : real

If set the image will be rotated by this many degrees before it is drawn.

The particle coordinates are not transformed.

rotationVariation : real

If set the rotation of individual particles will vary by up to this much between particles.

rotationVelocity : real

If set particles will rotate at this velocity in degrees/second.

rotationVelocityVariation : real

If set the rotationVelocity of individual particles will vary by up to this much between particles.

sizeTable : url

An image whose opacity will be used as a 1D texture to determine size over life.

This property is expected to be removed shortly, in favor of custom easing curves to determine size over life.

source : url

The source image to be used.

If the image is a sprite animation, use the sprite property instead.

Since Qt 5.2, some default images are provided as resources to aid prototyping:

qrc:///particleresources/star.png |
qrc:///particleresources/glowdot.png |
qrc:///particleresources/fuzzydot.png |

Note that the images are white and semi-transparent, to allow colorization and alpha levels to have maximum effect.

sprites : list<Sprite>

The sprite or sprites used to draw this particle.

Note that the sprite image will be scaled to a square based on the size of the particle being rendered.

For full details, see the Sprite Animations overview.

spritesInterpolate : bool

If set to true, sprite particles will interpolate between sprite frames each rendered frame, making the sprites look smoother.

Default is true.

status : Status

The status of loading the image.

xVector : StochasticDirection

Allows you to deform the particle image when drawn. The rectangular image will be deformed so that the horizontal sides are in the shape of this vector instead of (1,0).

yVector : StochasticDirection

Allows you to deform the particle image when drawn. The rectangular image will be deformed so that the vertical sides are in the shape of this vector instead of (0,1).