IParticle

IParticle (Partikelobjekt)

Inhaltsverzeichnis

1. Definition

Das Partikelobjekt ist vom Typ IParticle und leitet von ISlideShowObject ab. Mit diesem Objekt kann man Partikeleffekte erstellen.

Das Partikelobjekt enthält unter anderem Eigenschaften des Typs IParticleRangeValue bzw. IParticleVectorRangeValue. Einige dieser Eigenschaften verfügen über Initialwerte (wie Size und InitialSize). Die Initialwerte geben den Ausgangszustand des Wertes an, die Nicht-Initialwerte geben eine Änderung an. Die Initialwerte bekommen einen Wertebereich. Beim Emittieren eines Partikels wird dem neuen Partikel ein zufälliger Werte innerhalb dieses Bereichs zugewiesen. Initialwerte können sich über die Dauer des Partikelsystems ändern. Die Änderungswerte erhalten ebenfalls einen Bereich. Der Unterschied ist, dass bei ihnen vorher eine Wichtung ermittelt wird. Diese wird benutzt um die Änderungen über die Lebenszeit des Partikels immer gleich gewichtet zu haben (siehe Beispiel).

IParticle inherits from ISlideShowObject
  function InitialDirection: IParticleVectorRangeValue 
  function Direction: IParticleVectorRangeValue 
  function InitialSpeed: IParticleRangeValue  
  function Speed: IParticleRangeValue 
  function InitialSize: IParticleRangeValue 
  function Size: IParticleRangeValue 
  function InitialRotation: IParticleVectorRangeValue 
  function Rotation: IParticleVectorRangeValue 
  function InitialRotationFrequency: IParticleVectorRangeValue 
  function RotationFrequency: IParticleVectorRangeValue 
  function InitialOpacity: IParticleRangeValue 
  function Opacity: IParticleRangeValue

  property Move: TParticleMove 
  function InitialMoveStrength: IParticleVectorRangeValue 
  function MoveStrength: IParticleVectorRangeValue 
  function InitialMoveSineFrequency: IParticleRangeValue 
  function MoveSineFrequency: IParticleRangeValue

  function MaxAge: IParticleRangeValue 
  function ParticlesPerSecond: IParticleRangeValue

  property SpriteAnimation: TParticleSpriteAnimation 
  function InitialSpriteAnimationFrequency: IParticleRangeValue 
  function SpriteAnimationFrequency: IParticleRangeValue

  property Filename: IFilename 
  property Clipping: Boolean 
  property PreWarmTime: Integer

  property Emitter: TParticleEmitter
  function EmitterSpread: IParticleRangeValue
  procedure AddEmitterClipRect(const X, Y, Width, Height, AngleZ: Single; const Invert: Boolean);

  property Options: TParticleOptions
  property Environment: TParticleEnvironment

  property Seed: Int64  
end;

2. Methoden

2.1 Partikel

Bewegungsrichtung: Die Werte modifizieren einen Bewegungsvektor, der nach rechts zeigt. Die jeweiligen Richtungen geben Winkel an, um die der Vektor gedreht wird. Wichtig ist dabei die Reihenfolge. Als erstes wird der Winkel um die Z-Achse addiert, dann wird der Vektor um die Y-Achse gedreht und dann um die X-Achse.

Die Drehwinkel kann man sich anhand folgender Beispiele herleiten:

Drehwinkel um X und Y = 0 zeigt der Vektor bei Z = 0 (also der Basisvektor) nach rechts, bei Z = 90 zeigt der Vektor nach unten
Bei X = 0 und Z = 0, zeigt der Vektor bei Y = 90 nach hinten
Bei Z = 0 und Y = 90 zeigt der Vektor bei X = 90 nach oben
```
function InitialDirection: IParticleVectorRangeValue;
```

Richtungsänderung über die Zeit: Addition von Winkeln (zB. bei Initialrichtung von 10 und einer Richtung von 10 bekommt das Partikel die Richtung 20).
```
function Direction: IParticleVectorRangeValue;
```

Partikelgeschwindigkeit in Bewegungsrichtung

function InitialSpeed: IParticleRangeValue;

Geschwindigkeitsänderung über die Zeit: Prozent der Initialgeschwindigkeit.
```
function Speed: IParticleRangeValue;
```

Partikelgröße. Skaliert das Partikel ohne Verzerrung so, dass die größte Richtung die Partikelgröße wird ("einpassen"). Der Wert versteht sich in Prozent zu seinem Bezugssystem (siehe TParticleEnvironment):
```
function InitialSize: IParticleRangeValue;
```

Größenänderung über die Zeit: Prozent der Initialgröße.
```
function Size: IParticleRangeValue;
```

Partikeltransparenz

function InitialOpacity: IParticleRangeValue;

Transparenzänderung über die Zeit: Prozent der Initialtransparenz.
```
function Opacity: IParticleRangeValue;
```

Partikeldrehung: Man unterscheidet zwischen der statischen Lage des Partikels und einer beständigen Drehung. Beispielsweise sollen die Partikel beim Emittieren immer zwischen 10 und 20 Grad gedreht sein, die Lage aber behalten. Dafür kommt die Eigenschaft Rotation in Frage (bei einer Rotationsgeschwindigkeit von 0). Ist jedoch eine permanente Drehung gewünscht, nimmt man die Rotationfrequency (Rotationsgeschwindigkeit). Lage und Rotationsgeschwindigkeitschließen sich nicht aus. Positive Werte drehen im Uhrzeigersinn, negative entgegengesetzt. Die Werte verstehen sich als Winkeladditionen eines Basisvektoren, der die Standardrichtung angibt. Bei X = 0, Y = 0 und Z = 0 zeigt dieser Basisvektor nach rechts. Als erstes wird um Z rotiert, dann um Y, dann um X.

Lage des Partikels

function InitialRotation: IParticleVectorRangeValue;

Lageänderung über die Zeit. Additiv (zB. 10° bei 0ms und 20° bei 1000ms ergibt in der ersten Sekunde eine Drehung um 10°, danach keine weitere).
```
function Rotation: IParticleVectorRangeValue;
```

Rotationsgeschwindigkeit: Gibt die Anzahl der Drehungen in einer Sekunde an.
```
function InitialRotationFrequency: IParticleVectorRangeValue;
```

Geschwindigkeitsänderung die Zeit: Prozent der Initialgeschwindigkeit.
```
function RotationFrequency: IParticleVectorRangeValue;
```

Partikelbewegung: Partikel können neben ihrer eigentlichen Bewegungsrichtung auch von ihrer Bewegung abweichen, zum Beispiel schwingen.
```
property Move: TParticleMove;
```

Maximale Stärke der Abweichungsbewegung. Die Stärke ist in Prozent der maximalen Partikelgröße angegeben. Stärke = 100 heißt also, dass ein Partikel nach oben unten so weit ausschlägt, wie es selbst groß ist.
```
function InitialMoveStrength: IParticleVectorRangeValue;
```

Stärkenänderung über die Zeit: Prozent der Initialstärke:
```
function MoveStrength: IParticleVectorRangeValue;
```

Abweichungsfrequenz: Gibt an, wie viele Schwingungen oder Kreisbewegungen in einer Sekunde vollführt werden
```
function InitialMoveFrequency: IParticleRangeValue;
```

Frequenzänderung über die Zeit: Prozent der Initialfrequenz:
```
function MoveFrequency: IParticleRangeValue;
```

Lebensdauer des Partikels in Millisekunden. 0 heißt, dass das Partikel nie "stirbt".
```
function MaxAge: IParticleRangeValue;
```

Emittierrate. Gibt an, wie viele Partikel in einer Sekunde emittiert werden.
```
function ParticlesPerSecond: IParticleRangeValue;
```

Partikelanimation. Sind im Partikelsystem mehrere Bilddateien angegeben, können die Partikel ihr Bild während ihrer Lebenszeit ändern.
```
property SpriteAnimation: TParticleSpriteAnimation
```

Animationsgeschwindigkeit: Gibt die Anzahl der Bildwechsel pro Sekunde an
```
function InitialSpriteAnimationFrequency: IParticleRangeValue;
```

Geschwindigkeitsänderung über die Zeit: Prozent der Initialgeschwindigkeit.
```
function SpriteAnimationFrequency: IParticleRangeValue;
```

Dateinamen der Partikelbilder
```
property Filename: IFilename;
```

Partikelsystem auf seine Bounds zuschneiden oder alle Partikel, die hinausragen anzeigen:
```
property Clipping: Boolean;
```

Partikelsystem vorsimulieren. Es ist möglich, dass simuliert wird, dass das Partikelsystem bereits eine gewisse Zeit (in Millisekunden) gelaufen war, bevor es wirklich angezeigt wird. Mindestwert = 100ms
```
property PreWarmTime: Integer;
```

2.2 Emitter

Emitter-Typ:
```
property Emitter: TParticleEmitter
```

Rand am Emitter: Wenn der Emitter vom Typ pePoint oder pePath ist, kann er einen Abstand erhalten: Beim Punkt-Emitter werden die Partikel in einem Kreis mit angebenen Abstand emittiert, beim Pfad-Emitter werden die Partikel sowohl oberhalb als auch unterhalb davon abgebildet. Angabe in Prozent des Bildschirms.
```
function EmitterSpread: IParticleRangeValue
```

Flächen, an denen nicht emittiert werden soll: Der Emitter hält eine Liste von gedrehten Rechtecken, an denen nicht emittiert werden darf.
```
procedure AddEmitterClipRect(const X, Y, Width, Height, AngleZ: Single; const Exclude: Boolean);
```

2.3 Optionen

Partikel-Umgebung: Gibt an, ob die Bounds vom Partikelsystem nur als Positionierung der Partikel beim Emittieren dienen (peGlobal), oder ob das Partikelsystem Einfluss auf die Partikel hat, die Partikel also mitskalieren und sich mitdrehen, etc. (peLocal)
```
property Environment: TParticleEnvironment
```

Partikeloptionen geben beispielsweise an, wie sich die Partikel bei Drehung des Partikelsystems verhalten oder ob die Animationen abrupt oder durch Alphablending ablaufen. Einige Optionen sind nur für Environment = peGlobal sinnvoll:
```
property Options: TParticleOptions
```

Zufallswert (Seed), um wiederholbare Zufälle zu generieren. Ist der Wert = 0 werden alle Zufälle in den RangeValues wirklich zufällig berechnet, also immer ein eigener Seed generiert. Ansonsten wird der gegebene Seed verwendet.
```
property Seed: Int64;
```

3. Beispiel 1

Wird dieses Script einem Partikelobjekt zugeordnet, wird das Partikelsystem wie folgt konfiguriert:

Einem Partikelsystem werden folgende RangeValues gegeben:

InitialSize zwischen 10 und 20.
Size zwischen 50 und 100 ab 0ms und 0 und 50 ab 1000ms

Partikel 1 bekommt zufällig eine Größe zwischen 10 und 20, zB. 15. Der Size-Wert modifiziert diesen Initialwert, in dem Fall prozentual. Das heißt das Partikel ist zwischen 50% * 15 und 100% * 15 groß ab Sekunde 0 seiner Lebenszeit. Der genaue Wert wird durch die zufällig gewählte Wichtung ermittelt, sagen wir 50%. Die Wichtung legt also die Mitte des Bereichs fest. Demnach ist die Wichtung 75%, also die Mitte zwischen 50 und 100. Daher hat der Partikel zum Zeitpunkt 0ms (also dem Zeitpunkt seines Emittierens) die Größe 75% * 15 = 11,25. Der Size-Wert ändert sich über die Zeit. Allerdings bleibt die Wichtung pro Partikel gleich. Der Size-Wert sagt, dass die Partikel bei Sekunde 1 nur noch zwischen 0 und 50% des Initialwertes groß sind. Durch die Wichtung von 50% ergibt sich ein Size-Wert von 25%, also der Mitte zwischen 0 und 50%. Daher hat das Partikel zum Zeitpunkt 1000ms die Größe 25% * 15 = 3,75.

Für Partikel 2 wird eine neue Initialgröße vergeben (deren Bereich sich über die Zeit natürlich auch verändern kann). Ebenso wird eine neue Wichtung ermittelt, zB. Initialgröße von 12 und einer Wichtung von 100%. Demnach ist das Partikel 2 zum Zeitpunkt 0ms 12 Einheiten groß und nach einer Sekunde nur noch 6.

procedure OnExpandSlideShow(SlideShowObject: ISlideShowObject);
begin
  var Particle := SlideShowObject as IParticle;
  Particle.InitialSize.SetValue(0, 0, 10);
  Particle.InitialSize.SetValue(1, 0, 20);
  Particle.Size.SetValue(0, 0, 50);
  Particle.Size.SetValue(1, 0, 100);
  Particle.Size.SetValue(0, 1000, 0);
  Particle.Size.SetValue(1, 1000, 50);  
end;

4. Beispiel 2

Wird dieses Script einem Partikelobjekt zugeordnet, lässt es die Partikel um die X-Achse im 3D-Raum rotieren.

procedure OnExpandSlideShow(SlideShowObject: ISlideShowObject);
begin
  var ParticleObject: IParticle = SlideShowObject as IParticle;
   
  ParticleObject.InitialRotationFrequency.SetValueX(0, 0, 0.8); // Angabe in Hz   
end;