9728c89690400da9702bdb78200b1d9dc2ddf281
[blender.git] / source / blender / python / api2_2x / doc / Particle.py
1 # Blender.Object module and the Object PyType object
2
3 """
4 The Blender.Particle submodule
5
6
7 Particle
8 ========
9
10 This module provides access to the B{Particle} in Blender.
11
12 @type TYPE: readonly dictionary
13 @var TYPE: Constant dict used for with L{Particle.TYPE}
14                 - HAIR: set particle system to hair mode.
15                 - REACTOR: set particle system to reactor mode.
16                 - EMITTER: set particle system to emitter mode.
17 @type DISTRIBUTION: readonly dictionary
18 @var DISTRIBUTION: Constant dict used for with L{Particle.DISTRIBUTION}
19                 - GRID: set grid distribution.
20                 - RANDOM: set random distribution.
21                 - JITTERED: set jittered distribution.
22 @type EMITFROM: readonly dictionary
23 @var EMITFROM: Constant dict used for with L{Particle.EMITFROM}
24                 - VERTS: set particles emit from vertices
25                 - FACES: set particles emit from faces
26                 - VOLUME: set particles emit from volume
27                 - PARTICLE: set particles emit from particles
28 @type REACTON: readonly dictionary
29 @var REACTON: Constant dict used for with L{Particle.REACTON}
30                 - NEAR: react on near
31                 - COLLISION: react on collision
32                 - DEATH: react on death
33 @type DRAWAS: readonly dictionary
34 @var DRAWAS: Constant dict used for with L{Particle.DRAWAS}
35                 - NONE: Don't draw
36                 - POINT: Draw as point
37                 - CIRCLE: Draw as circles
38                 - CROSS: Draw as crosses
39                 - AXIS: Draw as axis
40                 - LINE: Draw as lines
41                 - PATH: Draw pathes
42                 - OBJECT: Draw object
43                 - GROUP: Draw goup
44                 - BILLBOARD: Draw as billboard 
45 @type CHILDTYPE: readonly dictionary
46 @var CHILDTYPE: Constant dict used for whith L{Particle.CHILDTYPE}
47                 - NONE: set no children
48                 - PARTICLES: set children born from particles
49                 - FACES: set children born from faces
50 """
51
52 class Particle:
53         """
54         The Particle object
55         ===================
56                 This object gives access to paticles data.
57                 
58         @ivar seed: Set an offset in the random table.
59         @type seed: int
60         @ivar type: Type of particle system ( Particle.TYPE[ 'HAIR' | 'REACTOR' | 'EMITTER' ] ).
61         @type type: int
62         @ivar resolutionGrid: The resolution of the particle grid.
63         @type resolutionGrid: int
64         @ivar startFrame: Frame number to start emitting particles.
65         @type startFrame: float
66         @ivar endFrame: Frame number to stop emitting particles.
67         @type endFrame: float
68         @ivar editable: Finalize hair to enable editing in particle mode.
69         @type editable: int
70         @ivar amount: The total number of particles.
71         @type amount: int
72         @ivar multireact: React multiple times ( Particle.REACTON[ 'NEAR' | 'COLLISION' | 'DEATH' ] ).
73         @type multireact: int
74         @ivar reactshape: Power of reaction strength, dependent on distance to target.
75         @type reactshape: float
76         @ivar hairSegments: Amount of hair segments.
77         @type hairSegments: int
78         @ivar lifetime: Specify the life span of the particles.
79         @type lifetime: float
80         @ivar randlife: Give the particle life a random variation.
81         @type randlife: float
82         @ivar randemission: Emit particles in random order.
83         @type randemission: int
84         @ivar particleDistribution: Where to emit particles from  ( Particle.EMITFROM[ 'PARTICLE' | 'VOLUME' | 'FACES' | 'VERTS' ] )
85         @type particleDistribution: int
86         @ivar evenDistribution: Use even distribution from faces based on face areas or edge lengths.
87         @type evenDistribution: int
88         @ivar distribution: How to distribute particles on selected element ( Particle.DISTRIBUTION[ 'GRID' | 'RANDOM' | 'JITTERED' ] ).
89         @type distribution: int
90         @ivar jitterAmount: Amount of jitter applied to the sampling.
91         @type jitterAmount: float
92         @ivar pf: Emission locations / face (0 = automatic).
93         @type pf:int
94         @ivar invert: Invert what is considered object and what is not.
95         @type invert: int
96         @ivar targetObject: The object that has the target particle system (empty if same object).
97         @type targetObject: Blender object
98         @ivar targetpsys: The target particle system number in the object.
99         @type targetpsys: int
100         @ivar 2d: Constrain boids to a surface.
101         @type 2d: float
102         @ivar maxvel: Maximum velocity.
103         @type maxvel: float
104         @ivar avvel: The usual speed % of max velocity.
105         @type avvel: float
106         @ivar latacc: Lateral acceleration % of max velocity
107         @type latacc: float
108         @ivar tanacc: Tangential acceleration % of max velocity
109         @type tanacc: float
110         @ivar groundz: Default Z value.
111         @type groundz: float
112         @ivar object: Constrain boids to object's surface.
113         @type object: Blender Object
114         @ivar renderEmitter: Render emitter object.
115         @type renderEmitter: int
116         @ivar displayPercentage: Particle display percentage.
117         @type displayPercentage: int
118         @ivar hairDisplayStep: How many steps paths are drawn with (power of 2) in visu mode.
119         @type hairDisplayStep: int
120         @ivar hairRenderStep: How many steps paths are rendered with (power of 2) in render mode."
121         @type hairRenderStep: int
122         @ivar duplicateObject: Get the duplicate object.
123         @type duplicateObject: Blender Object
124         @ivar drawAs: Get draw type Particle.DRAWAS([ 'NONE' | 'OBJECT' | 'POINT' | ... ]).
125         @type drawAs: int
126         @ivar childAmount: The total number of children
127         @type childAmount: int
128         @ivar childType: Type of childrens ( Particle.CHILDTYPE[ 'FACES' | 'PARTICLES' | 'NONE' ] )
129         @type childType: int
130         @ivar childRenderAmount: Amount of children/parent for rendering
131         @type childRenderAmount: int
132         @ivar childRadius: Radius of children around parent
133         @type childRadius: float
134         @ivar childRound: Roundness of children around parent
135         @type childRound: float
136         @ivar childClump: Amount of clumpimg
137         @type childClump: float
138         @ivar childShape: Shape of clumpimg
139         @type childShape: float
140         @ivar childSize: A multiplier for the child particle size
141         @type childSize: float
142         @ivar childRand: Random variation to the size of the child particles
143         @type childRand: float
144         @ivar childRough1: Amount of location dependant rough
145         @type childRough1: float
146         @ivar childRough1Size: Size of location dependant rough
147         @type childRough1Size: float
148         @ivar childRough2: Amount of random rough
149         @type childRough2: float
150         @ivar childRough2Size: Size of random rough
151         @type childRough2Size: float
152         @ivar childRough2Thresh: Amount of particles left untouched by random rough
153         @type childRough2Thresh: float
154         @ivar childRoughE: Amount of end point rough
155         @type childRoughE: float
156         @ivar childRoughEShape: Shape of end point rough
157         @type childRoughEShape: float
158         @ivar childKink: Type of periodic offset on the path (Particle.CHILDKINK[ 'BRAID' | 'WAVE' | 'RADIAL' | 'CURL' | 'NOTHING' ])
159         @type childKink: int
160         @ivar childKinkAxis: Which axis to use for offset (Particle.CHILDKINKAXIS[ 'Z' | 'Y' | 'X' ])
161         @type childKinkAxis: int
162         @ivar childKinkFreq: The frequency of the offset (1/total length)
163         @type childKinkFreq: float
164         @ivar childKinkShape: Adjust the offset to the beginning/end
165         @type childKinkShape: float
166         @ivar childKinkAmp: The amplitude of the offset
167         @type childKinkAmp: float
168         @ivar childBranch: Branch child paths from eachother
169         @type childBranch: int
170         @ivar childBranch: Animate branching
171         @type childBranch: int
172         @ivar childBranch: Start and end points are the same
173         @type childBranch: int
174         @ivar childBranch: Threshold of branching
175         @type childBranch: float
176         """
177         
178         def freeEdit():
179                 """
180                 Free edit mode.
181                 @return: None
182                 """
183
184         def getLoc(all=0,id=0):
185                 """
186                 Get the particles locations.
187                 A list of tuple is returned in particle mode.
188                 A list of list of tuple is returned in hair mode.
189                 The tuple is a vector of 3 or 4 floats in world space (x,y,z, optionally the particle's id).
190                 @type all: int
191                 @param all: if not 0 export all particles (uninitialized (unborn or died)particles exported as None).
192                 @type id: int
193                 @param id: add the particle id in the end of the vector tuple
194                 @rtype: list of vectors (tuple of 3 floats and optionally the id) or list of list of vectors
195                 @return: list of vectors or list of list of vectors (hair mode) or None if system is disabled
196                 """
197         def getRot(all=0,id=0):
198                 """
199                 Get the particles' rotations as quaternion.
200                 A list of tuple is returned in particle mode.
201                 The tuple is vector of 4 or 5 floats (x,y,z,w, optionally the id of the particle).
202                 
203                 @type all: int
204                 @param all: if not 0, export all particles (uninitialized (unborn or died) particles exported as None).
205                 @type id: int
206                 @param id: add the particle id in the return tuple
207                 @rtype: list of tuple of 4 or 5 elements (if id is not zero)
208                 @return: list of 4-tuples or None if system is disabled
209                 """
210                 
211         def getMat():
212                 """
213                 Get the particles' material.
214                 @rtype: Blender Material
215                 @return: The material assigned to particles
216                 """
217                 
218         def getSize(all=0,id=0):
219                 """
220                 Get the particles' size.
221                 A list of float or list of tuple (particle's size,particle's id).
222                 @type all: int
223                 @param all: if not 0, export all particles (uninitialized (unborn or died) particles exported as None).
224                 @type id: int
225                 @param id: add the particle id in the return tuple
226                 @rtype: list of floats
227                 @return: list of floats or list of tuples if id is not zero (size,id) or None if system is disabled.
228                 """
229                 
230         def getAge(all=0,id=0):
231                 """
232                 Get the particles' age.
233                 A list of float or list of tuple (particle's age, particle's id).
234                 @type all: int
235                 @param all: if not 0, export all particles (uninitialized (unborn or died) particles exported as None).
236                 @type id: int
237                 @param id: add the particle id in the return tuple
238                 @rtype: list of floats
239                 @return: list of floats or list of tuples if id is not zero (size,id) or None if system is disabled.
240                 """