AppleSCNParticleSystem - UBogun/Xojo-iosLib GitHub Wiki

Inherits from AppleObject
Memory leak check: not yet done.
Status: completed, but could maybe use convenience methods for the property constants.

An SCNParticleSystem object automatically creates, animates, and renders a system of particles—small image sprites—according to a high-level simulation whose general behavior you specify. Use particle systems to create effects such as smoke, rain, confetti, and fireworks.

Constructors

Constructor (): Creates a new particle system.

Constructor (ParticlesystemName as Text, inDirectoy as Text): Loads a particle system from a file in the app’s bundle resources.

Properties

Acceleration As SCNVector3: The constant acceleration vector, in units per second per second, applied to all particles in the system. Animatable. Default {0.0, 0.0, 0.0}

AffectedByGravity As Boolean: Whether gravity, as defined by the scene’s physics simulation, affects the motion of particles. Default False.

AffectedByPhsicsField As Boolean: Whether physics fields in the scene affect the motion of particles. Default False.

BirthDirection As SCNParticleBirthDirection: The possible initial directions for newly spawned particles, relative to the emitter shape. Default is ConstantDirection.

SCNParticleBirthDirection	Definition
Constant	The emitting direction is the same for all particles. When using this mode, the emittingDirection property determines the base direction for all particles, and the spreadingAngle property adds random variation to this direction.
SurfaceNormal	The emitting direction for each particle is along the surface normal vector at the point where the particle is emitted. The particle system creates new particles at points in space defined by the emitterShape geometry. When a new particle is emitted, the geometry’s surface normal vector at the point nearest the particle determines the particle’s initial direction. (Note that the birthLocation property defines where particles may be created relative to the emitterShape geometry.) This value has no effect if the emitterShape property value is nil.
RandomDirection	SceneKit randomizes the emitting direction for each particle.

BirthLocation As SCNParticleBirthLocation: The possible locations for newly spawned particles, relative to the emitter shape. Default is surface.

SCNParticleBirthLocation	Definition
Surface	New particles can be created at any location on the surface of the emitter shape.
Volume	New particles can be created at any location within the volume of the emitter shape. This value applies only when the emitterShape property specifies one of SceneKit’s built-in basic geometries (SCNPlane, SCNBox, SCNSphere, SCNPyramid, SCNCone, SCNCylinder, SCNCapsule, SCNTube, and SCNTorus).
Vertex	New particles can be created at only at the locations of the vertices in the emitter shape.

BirthRate As Double: The number of particles spawned during each emission period. Animatable. Default 1.0.

BirthRateVariation As Double: The range of randomized particle birth rate values. Animatable. Default 0.0.

BlackPassEnabled As Boolean: Whether SceneKit renders particles in black before rendering the particle image. Default False.

BlendMode As SCNParticleBlendMode: The blending mode for compositing particle images into the rendered scene.

SCNParticleBlendMode	Definition
Additive	The source and destination colors are added together.
Subtract	The source color is subtracted from the destination color.
Multiply	The source color is multiplied by the destination color.
Screen	The source color is added to the destination color times the inverted source color.
Alpha	The source and destination colors are blended by multiplying the source alpha value.
Replace	The source color replaces the destination color.

ColliderNodes As AppleArray Of AppleSCNNode: The nodes whose geometry the system’s particles can collide with.

DampingFactor As Double: A factor that slows particles relative to their velocity. Animatable.
A value of 0.0 (the default) specifies no slowing—that is, each particle maintains a constant speed (unless affected by gravity, acceleration, physics fields, or other influences). A value of 1.0 prevents particles from moving.

EmissionDuration As Double: The duration, in seconds, over which the system spawns new particles. Animatable. Default 1.0.

EmissionDurationVariation As Double: The range, in seconds, of randomized emission duration values. Animatable.

EmitterShape As AppleSCNGeometry: The shape of the region of space where the system spawns new particles. Default NIL – a single point.

EmittingDirection As AppleSCNVector3: The initial direction for newly spawned particles. Animatable. Default {0.0, 0.0, 1.0} – spawning in positive z direction.

FresnelExponent As Double: The reflectivity exponent SceneKit uses when rendering the particle’s image as a cube map. Animatable.

IdleDuration As Double: The duration, in seconds, of periods when the system emits no particles. Animatable. Default 0.0.

IdleDurationVariation As Double: The range, in seconds, of randomized idle duration values. Animatable.

ImageSequenceAnimationMode As SCNParticleImageSequenceAnimationMode: The animation mode for particle image animation.

SCNParticleImageSequenceAnimationMode	Definition
Repeat	The animation loops after displaying all of its images.
Clamp	The animation stops after displaying all of its images. After animation ends, the particle continues to display the last image of the sequence. (Or the first, if the animation is playing in reverse.)
AutoReverse	After the animation displays all of its images, it plays again in reverse order.

ImageSequenceColumnCount As Uinteger: The number of columns for treating the particle image as a grid of animation frames.

ImageSequenceFrameRate As Double: The rate, in frames per second, of particle image animation. Animatable. Default 0.0.

ImageSequenceFrameRateVariation As Double: The rate, in frames per second, of particle image animation. Animatable.

ImageSequenceInitialFrame As Double: The index of the first frame in a particle image animation. Animatable. Fractional values produce tween images. Default 0.0, top left image.

ImageSequenceInitialFrameVariation As Double: The range of randomized initial frames for particle image animation. Animatable.

ImageSequenceRowCount As UInteger: The number of rows for treating the particle image as a grid of animation frames.

LightingEnabled As Boolean: Whether SceneKit applies lighting to particle images when rendering.

Local As Boolean: Whether the particle simulation runs in the local coordinate space of the node containing it. Default False.

Loops As Boolean: Whether the system repeats its emission and idle periods. Default True.

Orientationmode As SCNParticleOrientationMode: The mode defining whether and how particles may rotate. Default ScreenAligned.

SCNParticleOrientationMode	Definition
ScreenAligned	Each particle’s orientation is always fixed with respect to the point of view camera. Use this mode for simple particle images whose individual appearance has no relation to scene space, such as spheres, circles, and “œsparkle” €artwork.
ViewAligned	Each particle always faces the point of view camera (but may rotate about an axis parallel to the view direction). Use this mode for particle images whose individual appearance depends on a location and orientation in scene space, such as “impostor” images representing trees or clouds in a scene.
Free	Particle orientations are not restricted; they may rotate freely in all axes. When using this mode, you can modify the rotation axis of each particle with the SCNParticlePropertyRotationAxis key.
YAligned	The y-axis direction of each particle is always fixed with respect to the point of view camera. Use this mode to allow each particle to rotate freely about its y-axis (as determined by the particleAngle and particleAngularVelocity properties or the SCNParticlePropertyAngle key), but prevent it from rotating around any other axis.

ParticleAngle As Double: The rotation angle, in degrees, of newly spawned particles. Animatable.

ParticleAngleVariation As Double: The range, in degrees, of randomized initial particle angles. Animatable.

ParticleAngularVelocity As Double: The initial spin rate, in degrees per second, of newly spawned particles. Animatable.

ParticleAngularVelocityVariation As Double: The range, in degrees per second, of randomized initial angular velocities for particles. Animatable.

ParticleBounce As Double: The restitution coefficient of each particle in the system. Animatable.
A value of 1.0 specifies that a particle loses no energy in a collision (for example, a particle that falls from a certain height onto a flat surface bounces back to the same height). Larger values specify energy gained, and smaller values specify a loss of energy. A value of 0.0 prevents particles from bouncing. You can randomize the bounce factors of particles in the system with the particleBounceVariation property. Default 0.7.

ParticleBounceVariation As Double: The restitution coefficient of each particle in the system. Animatable.

ParticleCharge As Double: The electric charge, in coulombs, of each particle in the system. Animatable.

ParticleChargeVariation As Double: ParticleCharge As Double: The electric charge, in coulombs, of each particle in the system. Animatable.

ParticleColor As AppleColor: The color of newly spawned particles. Animatable.

ParticleColorVariation As SCNVector4: The ranges of randomized particle color components. Animatable. Values are hue, saturation, brightness and alpha (in this order).

ParticleDiesOnCollision As Boolean: Whether particles are removed from the scene upon colliding with another object.

ParticleFriction As Double: The friction coefficient of each particle in the system. Animatable.

ParticleFriction As Double: The friction coefficient of each particle in the system. Animatable.
The default of 1.0 allows a particle to slide freely, and a value of 0.0 prevents a particle from sliding.

ParticleFrictionVariation As Double: The range of randomized friction coefficients for particles. Animatable.

ParticleImage As AppleObject: The texture image SceneKit uses to render each particle.
The particleColor property colorizes the image before rendering. You may specify an AppleImage, or a Text or AppleURLURL instance containing the path or URL to an image file. If the value is nil (the default), SceneKit renders each particle as a small white square (colorized by the particleColor property).
To specify a sequence of frames for animating each particle, arrange the frames as a grid in a single image, then use the properties listed in Animating Particle Images to identify frames in the grid and set the speed and style of the animation.

ParticleLifeSpan As Double: The duration, in seconds, for which each particle is rendered before being removed from the scene. Animatable. Default 1.0.

ParticleLifeSpanVariation As Double: The range, in seconds, of randomized particle life spans. Animatable.

ParticleMass As Double: The mass, in kilograms, of each particle in the system. Animatable. Default 1.0.

ParticleMassVariation As Double: The range, in kilograms, of randomized particle masses. Animatable.

ParticleSize As Double: The rendered size, in units of the scene’s world coordinate space, of the particle image. Animatable. Default 1.0.

ParticleSizeVariation As Double: The rendered size, in units of the scene’s world coordinate space, of the particle image. Animatable.

ParticleVelocity As Double: The initial speed, in units per second, for newly spawned particles. Animatable. Default 0.0.

ParticleVelocityVariation As Double: The initial speed, in units per second, for newly spawned particles. Animatable.

PropertyControllers As AppleDictionary: A dictionary that optionally associates particle properties with objects that animate a property’s value for each particle.
Each key in this dictionary is one of the constants available as shared text properties of this class, and the value for each key is a SCNParticlePropertyController object responsible for varying that property over time.

SortingMode As SCNSortingMode: The mode defining the order in which SceneKit renders the system’s particles.

SCNSortingMode	Definition
None	Particles are not sorted; they may be rendered in any order.
ProjectedDepth	Particles farther from the point of view (as measured using projected depth) are rendered before closer particles.
Distance	Particles farther from the point of view (as measured using distance from the camera in scene space) are rendered before closer particles.
OldestFirst	Particles emitted earlier are rendered before particles emitted more recently.
YoungestFirst	Particles emitted more recently are rendered before particles emitted earlier.

SpeedFactor As Double: A multiplier for the speed at which SceneKit runs the particle simulation. Animatable.

SpreadingAngle As Double: The range, in degrees, of randomized initial particle directions. Animatable. Default 0.0. Has no effect if BirthDirection is SCNParticleBirthDirection.Random.

StretchFactor As Double: A multiplier for stretching particle images along their direction of motion. Animatable.

SystemSpawnedOnCollision As AppleSCNParticleSystem: Another particle system to be added to the scene when a particle collides with scene geometry.

SystemSpawnedOnDying As AppleSCNParticleSystem: Another particle system to be added to the scene when a particle dies.

SystemSpawnedOnLyvingg As AppleSCNParticleSystem: Another particle system to be added to the scene for each living particle in the system.

WarmupDuration As Double: The duration, in seconds, for which particles are spawned before the system is first rendered. Animatable. Default 0.0.

Methods

AddModifiers (Properties As AppleArray, Stage As SCNParticleModifierStage, Block As AppleBlock): Adds a block that modifies particle properties, to be executed each time SceneKit renders a frame. See the SCNParticleModifierBlockTemplate private method of this class for the block structure.

SCNParticleModifierStage	Definition
PreDynamics	The stage before SceneKit simulates the motion of particles. Insert a modifier block at this stage to alter the inputs to the dynamics simulation. For example, if you modify the velocities of particles during this stage, SceneKit computes new positions for each particle based on its modified velocity.
PostDynamics	The stage after SceneKit simulates the motion of particles. Insert a modifier block at this stage to alter the output of the dynamics simulation. For example, if you modify the positions of particles during this stage, the modified positions override those determined by SceneKit’s simulation.
PreCollision	The stage before SceneKit simulates the results of collisions between particles and scene geometry. Insert a modifier block at this stage to alter the inputs to collision resolution. For example, if you modify the bounce factors of particles during this stage, SceneKit uses the modified factors to compute the bounce velocity of each particle.
PostCollision	The stage after SceneKit simulates the results of collisions between particles and scene geometry. Insert a modifier block at this stage to alter the output of collision resolution. For example, if you modify the velocities of particles during this stage, the modified velocities override the bounce velocity determined by SceneKit’s simulation.

AddParticleEvent (ParticleEvent As SCNParticleEvent, Properties as AppleArray, Block As AppleBlock): Adds a block that modifies particle properties, to be executed at a specified event in the lifetimes of particles in the system.
See the SCNParticleEventBlockTemplate private method of this class for the block structure.

SCNParticleEvent	Definition
Birth	Occurs when new particles spawn. Use a handler for this event to override the initial properties of each particle.
Death	Occurs when particles reach the end of their life span. SceneKit calls your event handler block immediately before removing dead particles from the scene.
Collision	Occurs when particles collide with scene geometry. SceneKit calls your event handler block immediately after resolving the collision.

RemoveAllModifiers(): Removes all particle modifier blocks associated with the particle system.

RemoveModifiers (Stage As SCNModifierStage): Removes particle modifier blocks for the specified stage of the particle simulation.

Reset(): Returns the particle system to its initial state.