Filling in branch from trunk
This commit is contained in:
Martin Poirier
590
source/blender/python/api2_2x/doc/Effect.py
Normal file
590
source/blender/python/api2_2x/doc/Effect.py
Normal file
@@ -0,0 +1,590 @@
|
||||
# Blender.Effect module and the Effect PyType effect
|
||||
|
||||
"""
|
||||
The Blender.Effect submodule
|
||||
|
||||
B{new}: now L{Get}('objname') (without specifying second parameter: 'position') returns a list of all effects linked to object "objname".
|
||||
|
||||
Effect
|
||||
======
|
||||
|
||||
INTRODUCTION
|
||||
|
||||
The Effect module allows you to access all the data of particle effects.
|
||||
An effect can modify a mesh object using particles, where vertex of
|
||||
the mesh emits particles, which can themselves emit new particles.
|
||||
|
||||
In the Blender internals, the effect object is just a placeholder for
|
||||
the particle effect. Prior to v2.39 build and wave effects were also
|
||||
supported by Blender, and the Python API supported all three types of
|
||||
effects. They were removed in v2.39 when the build and wave modifiers
|
||||
were implemented.
|
||||
|
||||
|
||||
Example::
|
||||
import Blender
|
||||
listffects = Blender.Effect.Get()
|
||||
print listeffects
|
||||
eff = listeffects[0]
|
||||
#we suppose the first effect is a build effect
|
||||
print eff.getLen()
|
||||
eff.setLen(500)
|
||||
|
||||
@type Flags: read-only dictionary
|
||||
@var Flags: The particle effect flags. Values can be ORed.
|
||||
- SELECTED: The particle effect is selected in the UI. (Read-only)
|
||||
- BSPLINE: Use a B-spline formula for particle interpolation
|
||||
- STATIC: Make static particles
|
||||
- ANIMATED: Recalculate static particles for each rendered frame
|
||||
- VERTS: Emit particles from vertices
|
||||
- FACES: Emit particles from faces
|
||||
- EVENDIST: Use even distribution based on face area (requires FACES)
|
||||
- TRUERAND: Use true random distribution based on face area (requires FACES)
|
||||
- UNBORN: Make particles appear before they are emitted
|
||||
- DIED: Make particles appear after they have died
|
||||
- EMESH: Render emitter mesh
|
||||
|
||||
@type SpeedTypes: read-only dictionary
|
||||
@var SpeedTypes: The available settings for selecting particle speed vectors.
|
||||
Only one setting is active at a time.
|
||||
- INTENSITY: Use texture intensity
|
||||
- RGB: Use RGB values
|
||||
- GRADIENT: Use texture gradient
|
||||
"""
|
||||
|
||||
def New (name):
|
||||
"""
|
||||
Creates a new particle effect and attaches to an object.
|
||||
@type name: string
|
||||
@param name: The name of object to associate with the effect. Only mesh
|
||||
objects are supported.
|
||||
@rtype: Blender Effect
|
||||
@return: the new effect
|
||||
"""
|
||||
|
||||
def Get (name = None, position = None):
|
||||
"""
|
||||
Get an Effect from Blender.
|
||||
@type name: string
|
||||
@param name: The name of object linked to the effect.
|
||||
@type position: int
|
||||
@param position: The position of the effect in the list of effects linked to the object.
|
||||
@rtype: Blender Effect or a list of Blender Effects
|
||||
@return: It depends on the 'objname, position' parameters:
|
||||
- (): A list with all Effects in the current scene;
|
||||
- (name): A list with all Effects linked to the given object;
|
||||
- (name, position): The Effect linked to the given object at the given position
|
||||
"""
|
||||
|
||||
class Effect:
|
||||
"""
|
||||
The Effect object
|
||||
=================
|
||||
This object gives access to particle effect data in Blender.
|
||||
|
||||
@ivar child: The number of children a particle may have.
|
||||
Values are clamped to the range [1,600].
|
||||
@type child: tuple of 4 ints
|
||||
@ivar childMat: The materials used by the 4 generation particles.
|
||||
Values are clamped to the range [1,16].
|
||||
@type childMat: tuple of 4 ints
|
||||
@ivar damping: The particle damping factor. This controls the rate at
|
||||
which particles decelerate.
|
||||
Values are clamped to the range [0.0,1.0].
|
||||
@type damping: float
|
||||
@ivar defvec: The x, y and z axis of the force defined by the texture.
|
||||
Values are clamped to the range [-1.0,1.0].
|
||||
@type defvec: tuple of 3 floats
|
||||
@ivar disp: The percentage of particles displayed.
|
||||
Value is clamped to the range [0,100].
|
||||
@type disp: int
|
||||
@ivar dispMat: The material used for the particles.
|
||||
Value is clamped to the range [1,16].
|
||||
@type dispMat: int
|
||||
@ivar emissionTex: The texture used for texture emission.
|
||||
Value is clamped to the range [1,10].
|
||||
@type emissionTex: int
|
||||
@ivar end: The end time of the effect.
|
||||
Value is clamped to the range [1.0,30000.0].
|
||||
@type end: float
|
||||
@ivar flag: The flag bitfield. See L{Flags} for values.
|
||||
@type flag: int
|
||||
@ivar force: The constant force applied to the parts.
|
||||
Values are clamped to the range [-1.0,1.0].
|
||||
@type force: tuple of 3 floats
|
||||
@ivar forceTex: The texture used for force.
|
||||
Value is clamped to the range [1,10].
|
||||
@type forceTex: int
|
||||
@ivar jitter: Jitter table distribution: maximum particles per face.
|
||||
Values are clamped to the range [0,200].
|
||||
@type jitter: int
|
||||
@ivar life: The lifetime of of the next generation of particles.
|
||||
Values are clamped to the range [1.0,30000.0].
|
||||
@type life: tuple of 4 floats
|
||||
@ivar lifetime: The lifetime of the effect.
|
||||
Value is clamped to the range [1.0,30000.0].
|
||||
@type lifetime: float
|
||||
@ivar mult: The probabilities of a particle having a child.
|
||||
Values are clamped to the range [0.0,1.0].
|
||||
@type mult: tuple of 4 floats
|
||||
@ivar nabla: The nabla value.
|
||||
Value is clamped to the range [0.0001,1.0].
|
||||
@type nabla: float
|
||||
@ivar normfac: The normal strength of the particles relative to mesh.
|
||||
Value is clamped to the range [-2.0,2.0].
|
||||
@type normfac: float
|
||||
@ivar obfac: The strength of the particles relative to objects.
|
||||
Value is clamped to the range [-1.0,1.0].
|
||||
@type obfac: float
|
||||
@ivar randfac: The initial random speed of the particles.
|
||||
Value is clamped to the range [0.0,2.0].
|
||||
@type randfac: float
|
||||
@ivar randlife: The variability of the life of the particles.
|
||||
Value is clamped to the range [0.0,2.0].
|
||||
@type randlife: float
|
||||
@ivar seed: The seed of the random number generator.
|
||||
Value is clamped to the range [0,255].
|
||||
@type seed: int
|
||||
@ivar speedType: Controls which texture property affects particle speeds.
|
||||
See L{SpeedTypes} for values and their meanings.
|
||||
@type speedType: int
|
||||
@ivar speedVGroup: The name of the vertex group used for speed control.
|
||||
@type speedVGroup: str
|
||||
@ivar sta: The start time of the effect.
|
||||
Value is clamped to the range [-250.0,30000.0].
|
||||
@type sta: float
|
||||
@ivar staticStep: percentage of skipped particles in static display.
|
||||
Value is clamped to the range [1,100].
|
||||
@type staticStep: int
|
||||
@ivar stype: The bitfield for vector.
|
||||
@type stype: int
|
||||
@ivar texfac: The initial speed of the particles caused by the texture.
|
||||
Value is clamped to the range [0.0,2.0].
|
||||
@type texfac: float
|
||||
@ivar totpart: The total number of particles.
|
||||
Value is clamped to the range [1,100000].
|
||||
@type totpart: int
|
||||
@ivar totkey: The total number of key positions.
|
||||
Value is clamped to the range [1,100].
|
||||
@type totkey: int
|
||||
@ivar type: The type of the effect. Deprecated.
|
||||
@type type: int
|
||||
@ivar vectsize: The size of vectors associated to the particles (if any).
|
||||
Value is clamped to the range [0.0,1.0].
|
||||
@type vectsize: float
|
||||
@ivar vGroup: The name of the vertex group used for emitted particles.
|
||||
@type vGroup: str
|
||||
"""
|
||||
|
||||
def getType():
|
||||
"""
|
||||
Retrieves the type of an effect object.
|
||||
Deprecated, since only particle effects are supported.
|
||||
@rtype: int
|
||||
@return: the type of an effect object : should always return 1
|
||||
(particle effect)
|
||||
"""
|
||||
|
||||
def setType(name):
|
||||
"""
|
||||
Deprecated, since only particle effects are supported.
|
||||
@type name: int
|
||||
@param name : the new type.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getFlag():
|
||||
"""
|
||||
Retrieves the flag of an effect object. The flag is a bit-mask.
|
||||
@rtype: int
|
||||
@return: The flag of the effect is a combination of parameters. See
|
||||
L{Flags} for values.
|
||||
|
||||
"""
|
||||
|
||||
def setFlag(newflag):
|
||||
"""
|
||||
Sets the flag of an effect object. See L{Flags} for values.
|
||||
@type newflag: int
|
||||
@param newflag: the new flag.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getStartTime():
|
||||
"""
|
||||
Retrieves the starting time of a particle effect object
|
||||
@rtype: float
|
||||
@return: the starting time of the effect.
|
||||
"""
|
||||
|
||||
def setSta(newstart):
|
||||
"""
|
||||
Sets the starting time of an particle effect object
|
||||
@type newstart: float
|
||||
@param newstart: the new starting time.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getEndTime():
|
||||
"""
|
||||
Retrieves the end time of a particle effect object
|
||||
@rtype: float
|
||||
@return: the end time of the effect.
|
||||
"""
|
||||
|
||||
def setEnd(newendrt):
|
||||
"""
|
||||
Sets the end time of an particle effect object
|
||||
@type newendrt: float
|
||||
@param newendrt: the new end time.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getLifetime():
|
||||
"""
|
||||
Retrieves the lifetime of a particle effect object
|
||||
@rtype: float
|
||||
@return: the lifetime of the effect.
|
||||
"""
|
||||
|
||||
|
||||
def setLifetime(newlifetime):
|
||||
"""
|
||||
Sets the lifetime of a particle effect object
|
||||
@type newlifetime: float
|
||||
@param newlifetime: the new lifetime.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getNormfac():
|
||||
"""
|
||||
Retrieves the normal strength of the particles (relatively to mesh).
|
||||
@rtype: float
|
||||
@return: normal strength of the particles (relatively to mesh).
|
||||
"""
|
||||
|
||||
def setNormfac(newnormfac):
|
||||
"""
|
||||
Sets the normal strength of the particles (relatively to mesh).
|
||||
@type newnormfac: float
|
||||
@param newnormfac: the normal strength of the particles (relatively to mesh).
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getObfac():
|
||||
"""
|
||||
Retrieves the initial strength of the particles relatively to objects.
|
||||
@rtype: float
|
||||
@return: initial strength of the particles (relatively to mesh).
|
||||
"""
|
||||
|
||||
def setObfac(newobfac):
|
||||
"""
|
||||
Sets the initial strength of the particles relatively to objects.
|
||||
@type newobfac: float
|
||||
@param newobfac: the initial strength of the particles relatively to objects.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getRandfac():
|
||||
"""
|
||||
Retrieves the random strength applied to the particles.
|
||||
@rtype: float
|
||||
@return: random strength applied to the particles.
|
||||
"""
|
||||
|
||||
def setRandfac(newrandfac):
|
||||
"""
|
||||
Sets the random strength applied to the particles.
|
||||
@type newrandfac: float
|
||||
@param newrandfac: the random strength applied to the particles.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getStype():
|
||||
"""
|
||||
Retrieves the vect state of an effect object.
|
||||
@rtype: int
|
||||
@return: the Stype (Vect) of an effect object : 0 , Vect is not enabled, 1, Vect is enabled
|
||||
(particle effect)
|
||||
"""
|
||||
|
||||
def setStype(int):
|
||||
"""
|
||||
@type int : int
|
||||
@param int : state of the Stype : 0 not enabled, 1 enabled.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getTexfac():
|
||||
"""
|
||||
Retrieves the strength applied to the particles from the texture of the object.
|
||||
@rtype: float
|
||||
@return: strength applied to the particles from the texture of the object.
|
||||
"""
|
||||
|
||||
def setTexfac(newtexfac):
|
||||
"""
|
||||
Sets the strength applied to the particles from the texture of the object.
|
||||
@type newtexfac: float
|
||||
@param newtexfac: the strength applied to the particles from the texture of the object.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getRandlife():
|
||||
"""
|
||||
Retrieves the variability of the life of the particles.
|
||||
@rtype: float
|
||||
@return: variability of the life of the particles.
|
||||
"""
|
||||
|
||||
def setRandlife(newrandlife):
|
||||
"""
|
||||
Sets the variability of the life of the particles.
|
||||
@type newrandlife: float
|
||||
@param newrandlife: the variability of the life of the particles.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getNabla():
|
||||
"""
|
||||
Retrieves the sensibility of the particles to the variations of the texture.
|
||||
@rtype: float
|
||||
@return: sensibility of the particles to the variations of the texture.
|
||||
"""
|
||||
|
||||
|
||||
def setNabla(newnabla):
|
||||
"""
|
||||
Sets the sensibility of the particles to the variations of the texture.
|
||||
@type newnabla: float
|
||||
@param newnabla: the sensibility of the particles to the variations of the texture.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getVectsize():
|
||||
"""
|
||||
Retrieves the size of the vector which is associated to the particles.
|
||||
@rtype: float
|
||||
@return: size of the vector which is associated to the particles.
|
||||
"""
|
||||
|
||||
|
||||
def setVectsize(newvectsize):
|
||||
"""
|
||||
Sets the size of the vector which is associated to the particles.
|
||||
@type newvectsize: float
|
||||
@param newvectsize: the size of the vector which is associated to the particles.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getTotpart():
|
||||
"""
|
||||
Retrieves the total number of particles.
|
||||
@rtype: int
|
||||
@return: the total number of particles.
|
||||
"""
|
||||
|
||||
|
||||
def setTotpart(newtotpart):
|
||||
"""
|
||||
Sets the the total number of particles.
|
||||
@type newtotpart: int
|
||||
@param newtotpart: the the total number of particles.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getTotkey():
|
||||
"""
|
||||
Retrieves the number of keys associated to the particles (kind of degree of freedom)
|
||||
@rtype: int
|
||||
@return: number of keys associated to the particles.
|
||||
"""
|
||||
|
||||
def setTotkey(newtotkey):
|
||||
"""
|
||||
Sets the number of keys associated to the particles.
|
||||
@type newtotkey: int
|
||||
@param newtotkey: number of keys associated to the particles.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getSeed():
|
||||
"""
|
||||
Retrieves the random number generator seed.
|
||||
@rtype: int
|
||||
@return: current seed value.
|
||||
"""
|
||||
|
||||
def setSeed(newseed):
|
||||
"""
|
||||
Sets the random number generator seed.
|
||||
@type newseed: int
|
||||
@param newseed: new seed value.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getForce():
|
||||
"""
|
||||
Retrieves the force applied to the particles.
|
||||
@rtype: tuple of three floats
|
||||
@return: force applied to the particles.
|
||||
"""
|
||||
|
||||
def setForce(newforce):
|
||||
"""
|
||||
Sets the force applied to the particles.
|
||||
@type newforce: tuple of 3 floats
|
||||
@param newforce: force applied to the particles.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getMult():
|
||||
"""
|
||||
Retrieves the probabilities of a particle having a child.
|
||||
@rtype: tuple of 4 floats
|
||||
@return: probabilities of a particle having a child.
|
||||
"""
|
||||
|
||||
def setMult(newmult):
|
||||
"""
|
||||
Sets the probabilities of a particle having a child.
|
||||
@type newmult: tuple of 4 floats
|
||||
@param newmult: probabilities of a particle having a child.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getLife():
|
||||
"""
|
||||
Retrieves the average life of the particles (4 generations)
|
||||
@rtype: tuple of 4 floats
|
||||
@return: average life of the particles (4 generations)
|
||||
"""
|
||||
|
||||
def setLife(newlife):
|
||||
"""
|
||||
Sets the average life of the particles (4 generations).
|
||||
@type newlife: tuple of 4 floats
|
||||
@param newlife: average life of the particles (4 generations).
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getChild():
|
||||
"""
|
||||
Retrieves the average number of children of the particles (4 generations).
|
||||
@rtype: tuple of 4 ints
|
||||
@return: average number of children of the particles (4 generations).
|
||||
"""
|
||||
|
||||
def setChild(newchild):
|
||||
"""
|
||||
Sets the average number of children of the particles (4 generations).
|
||||
@type newchild: tuple of 4 ints
|
||||
@param newchild: average number of children of the particles (4 generations).
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getMat():
|
||||
"""
|
||||
Retrieves the indexes of the materials associated to the particles (4 generations).
|
||||
@rtype: tuple of 4 ints
|
||||
@return: indexes of the materials associated to the particles (4 generations).
|
||||
"""
|
||||
|
||||
def setMat(newmat):
|
||||
"""
|
||||
Sets the indexes of the materials associated to the particles (4 generations).
|
||||
@type newmat: tuple of 4 ints
|
||||
@param newmat: the indexes of the materials associated to the particles (4 generations).
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getDefvec():
|
||||
"""
|
||||
Retrieves the x, y and z components of the force defined by the texture.
|
||||
@rtype: tuple of 3 floats
|
||||
@return: x, y and z components of the force defined by the texture.
|
||||
"""
|
||||
|
||||
def setDefvec(newdefvec):
|
||||
"""
|
||||
Sets the x, y and z components of the force defined by the texture.
|
||||
@type newdefvec: tuple of 3 floats
|
||||
@param newdefvec: the x, y and z components of the force defined by the
|
||||
texture.
|
||||
@rtype: None
|
||||
@return: None
|
||||
"""
|
||||
|
||||
def getParticlesLoc():
|
||||
"""
|
||||
Gets the location of each particle at the current time in worldspace.
|
||||
@rtype: A list of vector or a list of vector lists.
|
||||
@return: The coordinates of each particle at the current time.
|
||||
If the "Vect" option is enabled a list Vector pairs will be returned with a start and end point for each particle.
|
||||
When static particles are enabled, a list of lists will be returned, each item a strand of particles.
|
||||
|
||||
Example::
|
||||
|
||||
import Blender
|
||||
from Blender import Effect, Object
|
||||
scn= Blender.Scene.GetCurrent()
|
||||
ob= scn.getActiveObject()
|
||||
effect= ob.effects[0]
|
||||
particles= effect.getParticlesLoc()
|
||||
|
||||
# Check that particles are points only (not static and not vectors)
|
||||
if not effect.getFlag() & Effect.Flags.STATIC or not effect.getStype():
|
||||
for pt in particles:
|
||||
ob_empty= scn.objects.new('Empty')
|
||||
ob_empty.setLocation(pt)
|
||||
|
||||
else: # Particles will be a list
|
||||
for pt in particles:
|
||||
for pt_item in pt:
|
||||
ob_empty= scn.objects.new('Empty')
|
||||
ob_empty.setLocation(pt_item)
|
||||
|
||||
Example::
|
||||
# Converts particles into a mesh with edges for strands
|
||||
from Blender import Scene, Mathutils, Effect, Mesh, Object
|
||||
scn= Scene.GetCurrent()
|
||||
ob= scn.getActiveObject()
|
||||
me= Mesh.New()
|
||||
|
||||
effects= Effect.Get()
|
||||
for eff in effects:
|
||||
for p in eff.getParticlesLoc():
|
||||
# p is either a vector or a list of vectors. me.verts.extend() will deal with either
|
||||
print p
|
||||
me.verts.extend(p)
|
||||
|
||||
if type(p)==list: # Are we a strand or a pair, then add edges.
|
||||
if len(p)>1:
|
||||
edges= [(i, i+1) for i in range(len(me.verts)-len(p), len(me.verts)-1)]
|
||||
me.edges.extend( edges )
|
||||
|
||||
print len(me.verts)
|
||||
ob= scn.objects.new(me)
|
||||
"""
|
||||
Reference in New Issue
Block a user