Fix for bug [#13479] Particle system "corrupts" when changing material colour and...
[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 """
46
47 class Particle:
48         """
49         The Particle object
50         ===================
51                 This object gives access to paticles data.
52                 
53         @ivar seed: Set an offset in the random table.
54         @type seed: int
55         @ivar type: Type of particle system ( Particle.TYPE[ 'HAIR' | 'REACTOR' | 'EMITTER' ] ).
56         @type type: int
57         @ivar resolutionGrid: The resolution of the particle grid.
58         @type resolutionGrid: int
59         @ivar startFrame: Frame # to start emitting particles.
60         @type startFrame: float
61         @ivar endFrame: Frame # to stop emitting particles.
62         @type endFrame: float
63         @ivar editable: Finalize hair to enable editing in particle mode.
64         @type editable: int
65         @ivar amount: The total number of particles.
66         @type amount: int
67         @ivar multireact: React multiple times ( Paricle.REACTON[ 'NEAR' | 'COLLISION' | 'DEATH' ] ).
68         @type multireact: int
69         @ivar reactshape: Power of reaction strength dependence on distance to target.
70         @type reactshape: float
71         @ivar hairSegments: Amount of hair segments.
72         @type hairSegments: int
73         @ivar lifetime: Specify the life span of the particles.
74         @type lifetime: float
75         @ivar randlife: Give the particle life a random variation.
76         @type randlife: float
77         @ivar randemission: Give the particle life a random variation
78         @type randemission: int
79         @ivar particleDistribution: Where to emit particles from  Paricle.EMITFROM[ 'PARTICLE' | 'VOLUME' | 'FACES' | 'VERTS' ] )
80         @type particleDistribution: int
81         @ivar evenDistribution: Use even distribution from faces based on face areas or edge lengths.
82         @type evenDistribution: int
83         @ivar distribution: How to distribute particles on selected element Paricle.DISTRIBUTION[ 'GRID' | 'RANDOM' | 'JITTERED' ] ).
84         @type distribution: int
85         @ivar jitterAmount: Amount of jitter applied to the sampling.
86         @type jitterAmount: float
87         @ivar pf: Emission locations / face (0 = automatic).
88         @type pf:int
89         @ivar invert: Invert what is considered object and what is not.
90         @type invert: int
91         @ivar targetObject: The object that has the target particle system (empty if same object).
92         @type targetObject: Blender object
93         @ivar targetpsys: The target particle system number in the object.
94         @type targetpsys: int
95         @ivar 2d: Constrain boids to a surface.
96         @type 2d: float
97         @ivar maxvel: Maximum velocity.
98         @type maxvel: float
99         @ivar avvel: The usual speed % of max velocity.
100         @type avvel: float
101         @ivar latacc: Lateral acceleration % of max velocity
102         @type latacc: float
103         @ivar tanacc: Tangential acceleration % of max velocity
104         @type tanacc: float
105         @ivar groundz: Default Z value.
106         @type groundz: float
107         @ivar object: Constrain boids to object's surface.
108         @type object: Blender Object
109         @ivar renderEmitter: Render emitter object.
110         @type renderEmitter: int
111         @ivar displayPercentage: Particle display percentage.
112         @type displayPercentage: int
113         @ivar hairDisplayStep: How many steps paths are drawn with (power of 2) in visu mode.
114         @type hairDisplayStep: int
115         @ivar hairRenderStep: How many steps paths are rendered with (power of 2) in render mode."
116         @type hairRenderStep: int
117         @ivar duplicateObject: Get the duplicate object.
118         @type duplicateObject: Blender Object
119         @ivar drawAs: Get draw type Particle.DRAWAS([ 'NONE' | 'OBJECT' | 'POINT' | ... ]).
120         @type drawAs: int
121         """
122         
123         def freeEdit():
124                 """
125                 Free edit mode.
126                 @return: None
127                 """
128
129         def getLoc(all=0,id=0):
130                 """
131                 Get the particles locations.
132                 A list of tuple is returned in particle mode.
133                 A list of list of tuple is returned in hair mode.
134                 The tuple is a vector list of 3 or 4 floats in world space (x,y,z, optionnaly the particle's id).
135                 @type all: int
136                 @param all: if not 0 export all particles (uninitialized (unborn or died)particles exported as None).
137                 @type id: int
138                 @param id: add the particle id in the end of the vector tuple
139                 @rtype: list of vectors (tuple of 3 floats and optionnaly the id) or list of list of vectors
140                 @return: list of vectors or list of list of vectors (hair mode)
141                 """
142         def getRot(all=0,id=0):
143                 """
144                 Get the particles rotations as quaternion.
145                 A list of tuple is returned in particle mode.
146                 The tuple is a vector list of 4 or 5 floats (x,y,z,w, optionnaly the id of the particle).
147                 
148                 @type all: int
149                 @param all: if not 0 export all particles (uninitialized (unborn or died) particles exported as None).
150                 @type id: int
151                 @param id: add the particle id in the return tuple
152                 @rtype: list of tuple of 4 or 5 elements (if id is not zero)
153                 @return: list of 4-tuples
154                 """
155                 
156         def getMat():
157                 """
158                 Get the particles material.
159                 @rtype: Blender Material
160                 @return: The marterial assigned to particles
161                 """
162                 
163         def getSize(all=0,id=0):
164                 """
165                 Get the particles size.
166                 A list of float or list of tuple (particle's size,particle's id).
167                 @type all: int
168                 @param all: if not 0 export all particles (uninitialized (unborn or died) particles exported as None).
169                 @type id: int
170                 @param id: add the particle id in the return tuple
171                 @rtype: list of floats
172                 @return: list of floats or list of tuples if id is not zero (size,id).
173                 """
174                 
175         def getAge(all=0,id=0):
176                 """
177                 Get the particles age.
178                 A list of float or list of tuple (particle's age,particle's id).
179                 @type all: int
180                 @param all: if not 0 export all particles (uninitialized (unborn or died) particles exported as None).
181                 @type id: int
182                 @param id: add the particle id in the return tuple
183                 @rtype: list of floats
184                 @return: list of floats or list of tuples if id is not zero (size,id).
185                 """
186 # Blender.Object module and the Object PyType object
187
188 """
189 The Blender.Particle submodule
190
191
192 Particle
193 ========
194
195 This module provides access to the B{Particle} in Blender.
196
197 @type TYPE: readonly dictionary
198 @var TYPE: Constant dict used for with L{Particle.TYPE}
199                 - HAIR: set particle system to hair mode.
200                 - REACTOR: set particle system to reactor mode.
201                 - EMITTER: set particle system to emitter mode.
202 @type DISTRIBUTION: readonly dictionary
203 @var DISTRIBUTION: Constant dict used for with L{Particle.DISTRIBUTION}
204                 - GRID: set grid distribution.
205                 - RANDOM: set random distribution.
206                 - JITTERED: set jittered distribution.
207 @type EMITFROM: readonly dictionary
208 @var EMITFROM: Constant dict used for with L{Particle.EMITFROM}
209                 - VERTS: set particles emit from vertices
210                 - FACES: set particles emit from faces
211                 - VOLUME: set particles emit from volume
212                 - PARTICLE: set particles emit from particles
213 @type REACTON: readonly dictionary
214 @var REACTON: Constant dict used for with L{Particle.REACTON}
215                 - NEAR: react on near
216                 - COLLISION: react on collision
217                 - DEATH: react on death
218 @type DRAWAS: readonly dictionary
219 @var DRAWAS: Constant dict used for with L{Particle.DRAWAS}
220                 - NONE: Don't draw
221                 - POINT: Draw as point
222                 - CIRCLE: Draw as circles
223                 - CROSS: Draw as crosses
224                 - AXIS: Draw as axis
225                 - LINE: Draw as lines
226                 - PATH: Draw pathes
227                 - OBJECT: Draw object
228                 - GROUP: Draw goup
229                 - BILLBOARD: Draw as billboard 
230 """
231
232 def Get(name):
233                 """
234                 Get the particle system of the object "name".
235                 @type name: string
236                 @return: The particle system of the object.
237                 """
238 def New(name):
239                 """
240                 Assign a new particle system to the object "name".
241                 @type name: string
242                 @return: The newly created particle system.
243                 """
244
245 class Particle:
246         """
247         The Particle object
248         ===================
249                 This object gives access to paticles data.
250                 
251         @ivar seed: Set an offset in the random table.
252         @type seed: int
253         @ivar type: Type of particle system ( Particle.TYPE[ 'HAIR' | 'REACTOR' | 'EMITTER' ] ).
254         @type type: int
255         @ivar resolutionGrid: The resolution of the particle grid.
256         @type resolutionGrid: int
257         @ivar startFrame: Frame # to start emitting particles.
258         @type startFrame: float
259         @ivar endFrame: Frame # to stop emitting particles.
260         @type endFrame: float
261         @ivar editable: Finalize hair to enable editing in particle mode.
262         @type editable: int
263         @ivar amount: The total number of particles.
264         @type amount: int
265         @ivar multireact: React multiple times ( Paricle.REACTON[ 'NEAR' | 'COLLISION' | 'DEATH' ] ).
266         @type multireact: int
267         @ivar reactshape: Power of reaction strength dependence on distance to target.
268         @type reactshape: float
269         @ivar hairSegments: Amount of hair segments.
270         @type hairSegments: int
271         @ivar lifetime: Specify the life span of the particles.
272         @type lifetime: float
273         @ivar randlife: Give the particle life a random variation.
274         @type randlife: float
275         @ivar randemission: Give the particle life a random variation
276         @type randemission: int
277         @ivar particleDistribution: Where to emit particles from  Paricle.EMITFROM[ 'PARTICLE' | 'VOLUME' | 'FACES' | 'VERTS' ] )
278         @type particleDistribution: int
279         @ivar evenDistribution: Use even distribution from faces based on face areas or edge lengths.
280         @type evenDistribution: int
281         @ivar distribution: How to distribute particles on selected element Paricle.DISTRIBUTION[ 'GRID' | 'RANDOM' | 'JITTERED' ] ).
282         @type distribution: int
283         @ivar jitterAmount: Amount of jitter applied to the sampling.
284         @type jitterAmount: float
285         @ivar pf: Emission locations / face (0 = automatic).
286         @type pf:int
287         @ivar invert: Invert what is considered object and what is not.
288         @type invert: int
289         @ivar targetObject: The object that has the target particle system (empty if same object).
290         @type targetObject: Blender object
291         @ivar targetpsys: The target particle system number in the object.
292         @type targetpsys: int
293         @ivar 2d: Constrain boids to a surface.
294         @type 2d: float
295         @ivar maxvel: Maximum velocity.
296         @type maxvel: float
297         @ivar avvel: The usual speed % of max velocity.
298         @type avvel: float
299         @ivar latacc: Lateral acceleration % of max velocity
300         @type latacc: float
301         @ivar tanacc: Tangential acceleration % of max velocity
302         @type tanacc: float
303         @ivar groundz: Default Z value.
304         @type groundz: float
305         @ivar object: Constrain boids to object's surface.
306         @type object: Blender Object
307         @ivar renderEmitter: Render emitter object.
308         @type renderEmitter: int
309         @ivar displayPercentage: Particle display percentage.
310         @type displayPercentage: int
311         @ivar hairDisplayStep: How many steps paths are drawn with (power of 2) in visu mode.
312         @type hairDisplayStep: int
313         @ivar hairRenderStep: How many steps paths are rendered with (power of 2) in render mode."
314         @type hairRenderStep: int
315         @ivar duplicateObject: Get the duplicate object.
316         @type duplicateObject: Blender Object
317         @ivar drawAs: Get draw type Particle.DRAWAS([ 'NONE' | 'OBJECT' | 'POINT' | ... ]).
318         @type drawAs: int
319         """
320         def freeEdit():
321                 """
322                 Free edit mode.
323                 @return: None
324                 """
325
326         def getLoc(all=0,id=0):
327                 """
328                 Get the particles locations.
329                 A list of tuple is returned in particle mode.
330                 A list of list of tuple is returned in hair mode.
331                 The tuple is a vector list of 3 floats in world space.
332                 @type all: int
333                 @param all: if not 0 export all particles (uninitialized (unborn or died)particles exported as None).
334                 @type id: int
335                 @param id: add the particle id in the end of the vector tuple
336                 @rtype: list of vectors (tuple of 3 floats and optionnaly the id) or list of list of vectors
337                 @return: list of vectors or list of list of vectors (hair mode)
338                 """
339         def getRot(all=0,id=0):
340                 """
341                 Get the particles rotations as quaternion.
342                 A list of tuple is returned in particle mode.
343                 The tuple is a vector list of 4 floats (quaternion).
344                 @type all: int
345                 @param all: if not 0 export all particles (uninitialized (unborn or died) particles exported as None).
346                 @type id: int
347                 @param id: add the particle id in the return tuple
348                 @rtype: list of tuple of 4 or 5 elements (if id is not zero)
349                 @return: list of 4-tuples
350                 """
351         def getMat():
352                 """
353                 Get the particles material.
354                 @rtype: Blender Material
355                 @return: The marterial assigned to particles
356                 """
357         def getSize(all=0,id=0):
358                 """
359                 Get the particles size.
360                 A list of float.
361                 @type all: int
362                 @param all: if not 0 export all particles (uninitialized (unborn or died) particles exported as None).
363                 @type id: int
364                 @param id: add the particle id in the return tuple
365                 @rtype: list of floats
366                 @return: list of floats or list of tuples if id is not zero (size,id).
367                 """