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