1
2
3
4
5
6
7 """
8 The Blender.Texture submodule.
9
10 B{New}:
11 - many new attributes in L{MTex} submodule
12 - new dictionaries (L{Texture.BlendModes}, L{Texture.Mappings}, L{Texture.Proj}) to use for the values of some of the new L{MTex} attributes.
13
14 Texture
15 =======
16
17 This module provides access to B{Texture} objects in Blender.
18
19 Example::
20
21 from Blender import Texture,Image,Material
22
23 footex = Texture.Get('foo') # get texture named 'foo'
24 footex.setType('Image') # make foo be an image texture
25 img = Image.Load('test.png') # load an image
26 footex.image = img # link the image to the texture
27
28 mat = Material.Get('bar') # get a material
29 mtextures = mat.getTextures() # get a list of the MTex objects
30 for mtex in mtextures:
31 if mtex.tex.type == Texture.Types.IMAGE:
32 print mtex.tex.image.filename # print the filenames of all the
33 # images in textures linked to "bar"
34
35 mat.setTexture(0, footex) # set the material's first texture
36 # to be our texture
37
38
39 @type Types: readonly dictionary
40 @var Types: The available texture types:
41 - NONE - No texture
42 - CLOUDS - Clouds texture
43 - WOOD - Wood texture
44 - MARBLE - Marble texture
45 - MAGIC - Magic texture
46 - BLEND - Blend texture
47 - STUCCI - Stucci texture
48 - NOISE - Noise texture
49 - IMAGE - Image texture
50 - PLUGIN - Plugin texture
51 - ENVMAP - EnvMap texture
52 - MUSGRAVE - Musgrave procedural texture
53 - VORONOI - Voronoi procedural texture
54 - DISTNOISE - Distorted noise texture
55
56 @type Flags: readonly dictionary
57 @var Flags: The available Texture flags:
58 - FLIPBLEND - Flips the blend texture's X and Y directions
59 - NEGALPHA - Reverse the alpha value
60 - CHECKER_ODD - Fill the "odd" checkerboard tiles
61 - CHECKER_EVEN - Fill the "even" checkerboard tiles
62 - COLORBAND - Enable colorband for this texture
63 - PREVIEW_ALPHA - Show alpha in preview
64 - REPEAT_XMIR - Mirrors X direction repeat
65 - REPEAT_YMIR - Mirrors Y direction repeat
66
67 @type ImageFlags: readonly dictionary
68 @var ImageFlags: The available image flags for Texture.imageFlags:
69 - INTERPOL - Interpolate pixels of the image
70 - USEALPHA - Use the alpha layer
71 - MIPMAP - Enable mipmapping [cannot be used with FIELDS]
72 - FIELDS - Work with field images [cannot be used with MIPMAP]
73 - ROT90 - Rotate the image 90 degrees when rendering
74 - CALCALPHA - Calculate an alpha from the RGB
75 - STFIELD - Denotes this is a standard field
76 - MOVIE - Use a movie for an image
77 - CYCLIC - Repeat animation image
78 - ANTI - Use anti-aliasing
79 - NORMALMAP - Use image RGB values for normal mapping
80
81 @type ExtendModes: readonly dictionary
82 @var ExtendModes: Extend, clip, repeat or checker modes for image textures
83 - EXTEND - Extends the color of the edge
84 - CLIP - Return alpha 0.0 outside image
85 - CLIPCUBE - Return alpha 0.0 around cube-shaped area around image
86 - REPEAT - Repeat image vertically and horizontally
87 - CHECKER - Repeat image in checkerboard pattern
88
89 @type Noise: readonly dictionary
90 @var Noise: Noise types and bases. SINE, SAW and TRI are only used for
91 marble and wood textures, while the remainder are used for all textures
92 which has a noise basis function (for these textures, the constant should
93 be used with the second noise basis setting).
94 - SINE - Produce bands using sine wave (marble, wood textures)
95 - SAW - Produce bands using saw wave (marble, wood textures)
96 - TRI - Produce bands using triangle wave (marble, wood textures)
97 - BLENDER - Original Blender algorithm
98 - PERLIN - Ken Perlin's original (1985) algorithm
99 - IMPROVEDPERLIN - Ken Perlin's newer (2002) algorithm
100 - VORONOIF1 - none
101 - VORONOIF2 - none
102 - VORONOIF3 - none
103 - VORONOIF4 - none
104 - VORONOIF2F1 - none
105 - VORONOICRACKLE - none
106 - CELLNOISE - Steven Worley's cellular basis algorithm (1996)
107
108 @type BlendModes: readonly dictionary
109 @var BlendModes: The available texture blending modes:
110 - MIX - mix texture with value
111 - MULTIPLY - multiply texture with value
112 - ADD - add texture to value
113 - SUBTRACT - subtract texture from value
114 - DIVIDE - divide value by texture
115 - DARKEN - replace value with texture if texture is darker
116 - DIFFERENCE - difference of texture from value
117 - LIGHTEN - replace value with texture if texture is lighter
118 - SCREEN - 'screen' mode
119
120 @type Mappings: readonly dictionary
121 @var Mappings: The available 2D texture coordinate mappings for images:
122 - FLAT - flat projection
123 - CUBE - cube projection
124 - TUBE - cylindrical projection
125 - SPHERE - spherical projection
126
127 @type Proj: readonly dictionary
128 @var Proj: The available projections per axis:
129 - NONE - axis isn't used
130 - X - axis is used as final x axis
131 - Y - axis is used as final y axis
132 - Z - axis is used as final z axis
133
134 @type STypes: readonly dictionary
135 @var STypes: Texture-type specific data. Depending on the value of
136 Texture.type, certain groups will make sense. For instance, when a texture
137 is of type CLOUD, the CLD_xxx stypes can be used. Note that the first
138 value in each group is the default.
139 1. Clouds type
140 - CLD_DEFAULT - Monochromatic noise
141 - CLD_COLOR - RGB noise
142 2. Wood type
143 - WOD_BANDS - Use standard wood texture
144 - WOD_RINGS - Use wood rings
145 - WOD_BANDNOISE - Add noise to standard wood
146 - WOD_RINGNOISE - Add noise to rings
147 3. Magic type
148 - MAG_DEFAULT - Magic has no STypes
149 4. Marble type
150 - MBL_SOFT - Use soft marble
151 - MBL_SHARP - Use more clearly defined marble
152 - MBL_SHARPER - Use very clearly dfefined marble
153 5. Blend type
154 - BLN_LIN - Use a linear progression
155 - BLN_QUAD - Use a quadratic progression
156 - BLN_EASE - Uses a more complicated blend function
157 - BLN_DIAG - Use a diagonal progression
158 - BLN_SPHERE - Use a progression with the shape of a sphere
159 - BLN_HALO - Use a quadratic progression with the shape of a sphere
160 6. Stucci type
161 - STC_PLASTIC - Standard stucci
162 - STC_WALLIN - Creates dimples
163 - STC_WALLOUT - Creates ridges
164 7. Noise type
165 - NSE_DEFAULT - Noise has no STypes
166 8. Image type
167 - IMG_DEFAULT - Image has no STypes
168 9. Plugin type
169 - PLG_DEFAULT - Plugin has no STypes
170 10. Envmap type
171 - ENV_STATIC - Calculate map only once
172 - ENV_ANIM - Calculate map each rendering
173 - ENV_LOAD - Load map from disk
174 11. Musgrave type
175 - MUS_MFRACTAL - Hetero Multifractal
176 - MUS_RIDGEDMF - Ridged Multifractal
177 - MUS_HYBRIDMF - Hybrid Multifractal
178 - MUS_FBM - Fractal Brownian Motion
179 - MUS_HTERRAIN - Hetero Terrain
180 12. Voronoi type
181 - VN_INT - Only calculate intensity
182 - VN_COL1 - Color cells by position
183 - VN_COL2 - Same as Col1 plus outline based on F2-F1
184 - VN_COL3 - Same as Col2 multiplied by intensity
185 13. Distorted noise type
186 - DN_BLENDER - Original Blender algorithm
187 - DN_PERLIN - Ken Perlin's original (1985) algorithm
188 - DN_IMPROVEDPERLIN - Ken Perlin's newer (2002) algorithm
189 - DN_VORONOIF1 - none
190 - DN_VORONOIF2 - none
191 - DN_VORONOIF3 - none
192 - DN_VORONOIF4 - none
193 - DN_VORONOIF2F1 - none
194 - DN_VORONOICRACKLE - none
195 - DN_CELLNOISE - Steven Worley's cellular basis algorithm (1996)
196
197 @var TexCo: Flags for MTex.texco.
198 - ORCO - Use the original coordinates of the mesh
199 - REFL - Use reflection vector as texture coordinates
200 - NOR - Use normal vector as texture coordinates
201 - GLOB - Use global coordinates for the texture coordinates
202 - UV - Use UV coordinates for texture coordinates
203 - OBJECT - Use linked object's coordinates for texture coordinates
204 - WIN - Use screen coordinates as texture coordinates
205 - VIEW - Pass camera view vector on to the texture (World texture only!)
206 - STICK - Use mesh sticky coordinates for the texture coordinates
207 - STRESS - Use mesh stress coordinates for the texture coordinates
208 - TANGENT - Use mesh tangent coordinates for the texture coordinates
209 @type TexCo: readonly dictionary
210
211 @var MapTo: Flags for MTex.mapto.
212 - COL - Make the texture affect the basic color of the material
213 - NOR - Make the texture affect the rendered normal
214 - CSP - Make the texture affect the specularity color
215 - CMIR - Make the texture affect the mirror color
216 - REF - Make the texture affect the diffuse reflectivity value
217 - SPEC - Make the texture affect the specularity value
218 - HARD - Make the texture affect the hardness value
219 - ALPHA - Make the texture affect the alpha value
220 - EMIT - Make the texture affect the emit value
221 - RAYMIR - Make the texture affect the mirror reflectivity value
222 - DISP - Make the texture displace the mesh
223 - TRANSLU - Make the texture affect the translucency value
224 - AMB - Make the texture affect the ambient value
225 - WARP - Make the texture affect texture coordinates for the following textures
226 @type MapTo: readonly dictionary
227
228 """
229
230 -def New (name = 'Tex'):
231 """
232 Create a new Texture object.
233 @type name: string
234 @param name: The Texture name.
235 @rtype: Blender Texture
236 @return: The created Texture object.
237 """
238
239 -def Get (name = None):
240 """
241 Get the Texture object(s) from Blender.
242 @type name: string
243 @param name: The name of the Texture.
244 @rtype: Blender Texture or a list of Blender Textures
245 @return: It depends on the I{name} parameter:
246 - (name): The Texture object with the given I{name};
247 - (): A list with all Texture objects in the current scene.
248 """
249
250 from IDProp import IDGroup, IDArray
252 """
253 The Texture object
254 ==================
255 This object gives access to Texture-specific data in Blender.
256
257 Note that many of the attributes of this object are only relevant for
258 specific texture types.
259
260 @ivar animFrames: Number of frames of a movie to use.
261 Value is clamped to the range [0,300000].
262 @type animFrames: int
263 @ivar animOffset: Offsets the number of the first movie frame to use.
264 Value is clamped to the range [-300000,300000].
265 @type animOffset: int
266 @ivar animStart: Starting frame of the movie to use.
267 Value is clamped to the range [1,300000].
268 @type animStart: int
269 @ivar anti: Image anti-aliasing enabled. Also see L{ImageFlags}.
270 @type anti: int
271 @ivar brightness: Changes the brightness of a texture's color.
272 Value is clamped to the range [0.0,2.0].
273 @type brightness: float
274 @ivar calcAlpha: Calculation of image's alpha channel enabled. Also see L{ImageFlags}.
275 @type calcAlpha: int
276 @ivar contrast: Changes the contrast of a texture's color.
277 Value is clamped to the range [0.01,5.0].
278 @type contrast: float
279 @ivar crop: Sets the cropping extents (for image textures).
280 @type crop: tuple of 4 ints
281 @ivar cyclic: Looping of animated frames enabled. Also see L{ImageFlags}.
282 @type cyclic: boolean
283 @ivar distAmnt: Amount of distortion (for distorted noise textures).
284 Value is clamped to the range [0.0,10.0].
285 @type distAmnt: float
286 @ivar distMetric: The distance metric (for Voronoi textures).
287 @type distMetric: int
288 @ivar exp: Minkovsky exponent (for Minkovsky Voronoi textures).
289 Value is clamped to the range [0.01,10.0].
290 @type exp: float
291 @ivar extend: Texture's 'Extend' mode (for image textures). See L{ExtendModes}.
292 @type extend: int
293 @ivar fields: Use of image's fields enabled. Also see L{ImageFlags}.
294 @type fields: int
295 @ivar fieldsPerImage: Number of fields per rendered frame.
296 Value is clamped to the range [1,200].
297 @type fieldsPerImage: int
298 @ivar filterSize: The filter size (for image and envmap textures).
299 Value is clamped to the range [0.1,25.0].
300 @type filterSize: float
301 @ivar flags: Texture's 'Flag' bitfield. See L{Flags}.
302 bitmask.
303 @type flags: int
304 @ivar hFracDim: Highest fractional dimension (for Musgrave textures).
305 Value is clamped to the range [0.0001,2.0].
306 @type hFracDim: float
307 @ivar iScale: Intensity output scale (for Musgrave and Voronoi textures).
308 Value is clamped to the range [0.0,10.0].
309 @type iScale: float
310 @ivar image: Texture's image object.
311 @type image: Blender Image (or None)
312 @ivar imageFlags: Texture's 'ImageFlags' bits.
313 @type imageFlags: int
314 @ivar interpol: Interpolate image's pixels to fit texture mapping enabled. Also see L{ImageFlags}.
315 @type interpol: int
316 @ivar ipo: Texture Ipo data.
317 Contains the Ipo if one is assigned to the object, B{None} otherwise. Setting to B{None} clears the current Ipo..
318 @type ipo: Blender Ipo
319 @ivar lacunarity: Gap between succesive frequencies (for Musgrave textures).
320 Value is clamped to the range [0.0,6.0].
321 @type lacunarity: float
322 @ivar mipmap: Mipmaps enabled. Also see L{ImageFlags}.
323 @type mipmap: int
324 @ivar movie: Movie frames as images enabled. Also see L{ImageFlags}.
325 @type movie: int
326 @ivar noiseBasis: Noise basis type (wood, stucci, marble, clouds,
327 Musgrave, distorted). See L{Noise} dictionary.
328 @type noiseBasis: int
329 @ivar noiseBasis2: Additional noise basis type (wood, marble, distorted
330 noise). See L{Noise} dictionary.
331 @type noiseBasis2: int
332 @ivar noiseDepth: Noise depth (magic, marble, clouds).
333 Value is clamped to the range [0,6].
334 @type noiseDepth: int
335 @ivar noiseSize: Noise size (wood, stucci, marble, clouds, Musgrave,
336 distorted noise).
337 Value is clamped to the range [0.0001,2.0].
338 @type noiseSize: float
339 @ivar noiseType: Noise type (for wood, stucci, marble, clouds textures). Valid values are 'hard' or 'soft'.
340 @type noiseType: string
341 @ivar normalMap: Use of image RGB values for normal mapping enabled.
342 Also see L{ImageFlags}.
343 @type normalMap: int
344 @ivar octs: Number of frequencies (for Musgrave textures).
345 Value is clamped to the range [0.0,8.0].
346 @type octs: float
347 @ivar repeat: Repetition multiplier (for image textures).
348 @type repeat: tuple of 2 ints
349 @ivar rgbCol: RGB color tuple.
350 @type rgbCol: tuple of 3 floats
351 @ivar rot90: X/Y flip for rendering enabled. Also see L{ImageFlags}.
352 @type rot90: int
353 @ivar saw: Produce bands using saw wave (marble, wood textures). Also see L{Noise}.
354 @type saw: int
355 @ivar sine: Produce bands using sine wave (marble, wood textures). Also see L{Noise}.
356 @type sine: int
357 @ivar stField: Standard field deinterlacing enabled. Also see L{ImageFlags}.
358 @type stField: int
359 @ivar stype: Texture's 'SType' mode. See L{STypes}.
360 @type stype: int
361 @ivar tri: Produce bands using triangle wave (marble, wood textures). Also see L{Noise}.
362 @type tri: int
363 @ivar turbulence: Turbulence (for magic, wood, stucci, marble textures).
364 Value is clamped to the range [0.0,200.0].
365 @type turbulence: float
366 @ivar type: Texture's 'Type' mode. See L{Types}.
367 Value must be in the range [0,13].
368 @type type: int
369 @ivar useAlpha: Use of image's alpha channel enabled. Also see L{ImageFlags}.
370 @type useAlpha: int
371 @ivar weight1: Weight 1 (for Voronoi textures).
372 Value is clamped to the range [-2.0,2.0].
373 @type weight1: float
374 @ivar weight2: Weight 2 (for Voronoi textures).
375 Value is clamped to the range [-2.0,2.0].
376 @type weight2: float
377 @ivar weight3: Weight 3 (for Voronoi textures).
378 Value is clamped to the range [-2.0,2.0].
379 @type weight3: float
380 @ivar weight4: Weight 4 (for Voronoi textures).
381 Value is clamped to the range [-2.0,2.0].
382 @type weight4: float
383 @ivar colorband: Texture colorband, a list of colors,
384 each color a list of 5 floats [0 - 1], [r,g,b,a,pos].
385 The colorband can have between 1 and 31 colors.
386 @type colorband: list
387 @ivar autoRefresh: Refresh image on frame changes enabled.
388 @type autoRefresh: boolean
389 """
390
392 """
393 Get the extend mode of the texture. See L{setExtend}.
394 @rtype: string.
395 """
396
398 """
399 Get the Image associated with this texture (or None).
400 @rtype: Blender Image
401 """
402
404 """
405 Get the name of this Texture object.
406 @rtype: string
407 """
408
410 """
411 Get this Texture's type. See L{setType}.
412 @rtype: string
413 """
414
415 - def setExtend(extendmode):
416 """
417 Set the extend mode of this texture (only used for IMAGE textures)
418 @param extendmode: The new extend mode. One of:
419 'Extend', 'Clip', 'ClipCube' and 'Repeat'
420 @type extendmode: string
421 """
422
423 - def setFlags(f1=None, f2=None, f3=None, f4=None):
424 """
425 Set this object's flags.
426 @param f1,f2,f3,f4: Flags to be set (omitted flags are cleared). Can be any of
427 'FlipBlendXY', 'NegAlpha', 'CheckerOdd', and 'CheckerEven'
428 @type f1,f2,f3,f4: string
429 """
430
431 - def setImage(image):
432 """
433 Set the Image of this texture.
434 @param image: The new Image.
435 @type image: Blender Image or None.
436 @warning: This sets the texture's type to 'Image' if it is not already.
437 """
438
439 - def setImageFlags(f1=None, f2=None, f3=None, etc=None):
440 """
441 Set the Image flags (only makes sense for IMAGE textures). Omitted
442 flags are cleared.
443 @param f1, f2, f3, etc: Flag to set. See L{ImageFlags} for their meanings. Can be
444 any of: 'InterPol', 'UseAlpha', 'MipMap', 'Fields', 'Rot90',
445 'CalcAlpha', 'Cyclic', 'Movie', 'StField', 'Anti' and 'NormalMap'
446 @type f1, f2, f3, etc: string
447 """
448
450 """
451 Set the name of this Texture object.
452 @param name: The new name.
453 @type name: string
454 """
455
456 - def setSType(stype):
457 """
458 Set the SType.
459 @param stype: The new stype. This can be any of the values listed in
460 L{STypes} or 'Default' which sets the stype to the default value.
461 @type stype: string
462
463 @note: the set of valid parameters is dependent on the current
464 texture type. Be sure to always set the texture type B{before}
465 setting the texture's stype; otherwise an exception might occur.
466 """
467
469 """
470 Set this Texture's type.
471 @param type: The new type. Possible options are:
472 'None', 'Clouds', 'Wood', 'Marble', 'Magic', 'Blend', 'Stucci',
473 'Noise', 'Image', 'Plugin', 'EnvMap', 'Musgrave', 'Voronoi'
474 and 'DistNoise'
475 @type type: string
476 """
477 - def evaluate(coord):
478 """
479 Evaluates the texture at this location and returns the result.
480
481 The return value is a 4D vector where (x,y,z,w) are (red, green, blue, intensity)
482 For greyscale textures, often intensity only will be used.
483 @type coord: vector or tuple of 3 numbers
484 """
485
486 import id_generics
487 Texture.__doc__ += id_generics.attributes
488
490 """
491 The MTex Object
492 ===============
493
494 This object links a material to a texture. It allows the same texture to be
495 used in several different ways.
496
497 @ivar tex: The Texture this is linked to.
498 @type tex: Blender Texture
499 @ivar texco: Texture coordinates ("Map input"). See L{TexCo}
500 @ivar mapto: "Map to" field of texture. OR'd values of L{MapTo}
501 @ivar object: Object whose space to use when texco is Object
502 @type object: Blender Object
503 @ivar col: Color that the texture blends with
504 @ivar dvar: Value that the texture blends with when not blending colors
505 @ivar blendmode: Texture blending mode. L{BlendModes}
506 @ivar colfac: Factor by which texture affects color
507 @ivar norfac: Factor by which texture affects normal
508 @ivar varfac: Factor by which texture affects most variables
509 @ivar dispfac: Factor by which texture affects displacement
510 @ivar warpfac: Factor by which texture affects warp
511 @ivar ofs: Offset to adjust texture space
512 @ivar size: Size to scale texture space
513 @ivar mapping: Mapping of texture coordinates (flat, cube, etc.). L{Mappings}
514 @ivar stencil: Stencil mode
515 @ivar neg: Negate texture values mode
516 @ivar noRGB: Convert texture RGB values to intensity values
517 @ivar correctNor: Correct normal mapping for Texture space and Object space
518 @ivar fromDupli: Dupli's instanced from verts, faces or particles, inherit texture coordinate from their parent
519 @ivar fromOrig: Dupli's derive their object coordinates from the original objects transformation
520 @ivar xproj: Projection of X axis to Texture space. L{Proj}
521 @ivar yproj: Projection of Y axis to Texture space. L{Proj}
522 @ivar zproj: Projection of Z axis to Texture space. L{Proj}
523 @ivar mtCol: How texture maps to color
524 @ivar mtNor: How texture maps to normals
525 @ivar mtCsp: How texture maps to specularity color
526 @ivar mtCmir: How texture maps to mirror color
527 @ivar mtRef: How texture maps to reflectivity
528 @ivar mtSpec: How texture maps to specularity
529 @ivar mtEmit: How texture maps to emit value
530 @ivar mtAlpha: How texture maps to alpha value
531 @ivar mtHard: How texture maps to hardness
532 @ivar mtRayMir: How texture maps to RayMir value
533 @ivar mtTranslu: How texture maps to translucency
534 @ivar mtAmb: How texture maps to ambient value
535 @ivar mtDisp: How texture maps to displacement
536 @ivar mtWarp: How texture maps to warp
537 @ivar uvlayer: The name of the UV Layer this texture is mapped to (when left blank uses render layer)
538 @type uvlayer: string
539 """
540
542 """
543 Get the Ipo associated with this texture object, if any.
544 @rtype: Ipo
545 @return: the wrapped ipo or None.
546 """
547
549 """
550 Link an ipo to this texture object.
551 @type ipo: Blender Ipo
552 @param ipo: a "texture data" ipo.
553 """
554
556 """
557 Unlink the ipo from this texture object.
558 @return: True if there was an ipo linked or False otherwise.
559 """
560