Bugfix for python Image.save()
[blender.git] / source / blender / python / api2_2x / doc / Image.py
1 # Blender.Image module and the Image PyType object
2
3 """
4 The Blender.Image submodule.
5
6 Image
7 =====
8
9 B{New}: L{Image.clampX}, L{Image.clampY}.
10
11 This module provides access to B{Image} objects in Blender.
12
13 Example::
14         import Blender
15         from Blender import Image
16         #
17         image = Image.Load("/path/to/my/image.png")    # load an image file
18         print "Image from", image.getFilename(),
19         print "loaded to obj", image.getName())
20         image.setXRep(4)                               # set x tiling factor
21         image.setYRep(2)                               # set y tiling factor
22         print "All Images available now:", Image.Get()
23
24 @type Sources: readonly dictionary
25 @var Sources: The available Image Source.
26                 - STILL: Single image file
27                 - MOVIE: Movie file
28                 - SEQUENCE: Multiple image files, as sequence
29                 - GENERATED: Generated image
30 """
31
32 def Load (filename):
33         """
34         Load the image called 'filename' into an Image object.
35         @type filename: string
36         @param filename: The full path to the image file.
37         @rtype:  Blender Image
38         @return: A Blender Image object with the data from I{filename}.
39         """
40
41 def New (name, width, height, depth):
42         """
43         Create a new Image object.
44         @type name: string
45         @param name: The name of the new Image object.
46         @type width: int
47         @param width: The width of the new Image object, between 1 and 5000.
48         @type height: int
49         @param height: The height of the new Image object, between 1 and 5000.
50         @type depth: int
51         @param depth: The colour depth of the new Image object. (8:Grey, 24:RGB, 32:RGBA). (Not implimented yet, all new images will be 24bit)
52         @rtype: Blender Image
53         @return: A new Blender Image object.
54         """
55
56 def Get (name = None):
57         """
58         Get the Image object(s) from Blender.
59         @type name: string
60         @param name: The name of the Image object.
61         @rtype: Blender Image or a list of Blender Images
62         @return: It depends on the I{name} parameter:
63                         - (name): The Image object called I{name}, None if not found;
64                         - (): A list with all Image objects in the current scene.
65         """
66
67 def GetCurrent ():
68         """
69         Get the currently displayed Image from Blenders UV/Image window.
70         When multiple images are displayed, the last active UV/Image windows image is used.
71         @rtype: Blender Image
72         @return: The Current Blender Image, If there is no current image it returns None.
73         """
74
75 from IDProp import IDGroup, IDArray
76 class Image:
77         """
78         The Image object
79         ================
80                 This object gives access to Images in Blender.
81         @ivar filename: The filename (path) to the image file loaded into this Image
82                  object.
83         @type filename: string
84         @ivar size: The [width, height] dimensions of the image (in pixels).
85         @type size: list
86         @ivar depth: The pixel depth of the image. [8, 16, 18, 24, 32]
87         @type depth: int
88         @ivar xrep: Texture tiling: the number of repetitions in the x (horizontal)
89                  axis. [1, 16].
90         @ivar yrep: Texture tiling: the number of repetitions in the y (vertical)
91                  axis [1, 16].
92         @type xrep: int 
93         @type yrep: int 
94         @ivar start: Texture's animation start frame [0, 128].
95         @type start: int
96         @ivar end: Texture's animation end frame [0, 128].
97         @type end: int
98         @ivar speed: Texture's animation speed [1, 100].
99         @type speed: int
100         @ivar packed: True when the Texture is packed (readonly).
101         @type packed: boolean
102         @ivar has_data: True when the image has pixel data (readonly).
103         @type has_data: boolean
104         @ivar fields: enable or disable the fields option for this image.
105         @type fields: boolean
106         @ivar fields_odd: enable or disable the odd fields option for this image.
107         @type fields_odd: boolean
108         @ivar antialias: enable or disable the antialias option for this image.
109         @type antialias: boolean
110         @ivar bindcode: Texture's bind code (readonly).
111         @type bindcode: int
112         @ivar source: Image source type.  See L{the Sources dictionary<Sources>} .
113         @type source: int
114         @ivar clampX: When true the image will not tile horizontally.
115         @type clampX: bool
116         @ivar clampY: When true the image will not tile vertically.
117         @type clampY: bool
118         """
119
120         def getName():
121                 """
122                 Get the name of this Image object.
123                 @rtype: string
124                 """
125
126         def getFilename():
127                 """
128                 Get the filename of the image file loaded into this Image object.
129                 @rtype: string
130                 """
131
132         def getSize():
133                 """
134                 Get the [width, height] dimensions (in pixels) of this image.
135                 @rtype: list of 2 ints
136                 """
137
138         def getDepth():
139                 """
140                 Get the pixel depth of this image.
141                 @rtype: int
142                 """
143
144         def getPixelF(x, y):
145                 """
146                 Get the the colors of the current pixel in the form [r,g,b,a].
147                 Returned values are floats normalized to 0.0 - 1.0.
148                 Pixel coordinates are in the range from 0 to N-1.  See L{getMaxXY}
149                 @returns: [ r, g, b, a]
150                 @rtype: list of 4 floats
151                 @type x: int
152                 @type y: int
153                 @param x:  the x coordinate of pixel.
154                 @param y:  the y coordinate of pixel.  
155                 """
156         def getPixelI(x, y):
157                 """
158                 Get the the colors of the current pixel in the form [r,g,b,a].
159                 Returned values are ints normalized to 0 - 255.
160                 Pixel coordinates are in the range from 0 to N-1.  See L{getMaxXY}
161                 @returns: [ r, g, b, a]
162                 @rtype: list of 4 ints
163                 @type x: int
164                 @type y: int
165                 @param x:  the x coordinate of pixel.
166                 @param y:  the y coordinate of pixel.  
167                 """
168
169         def getMaxXY():
170                 """
171                 Get the  x & y size for the image.  Image coordinates range from 0 to size-1.
172                 @returns: [x, y]
173                 @rtype: list of 2 ints
174                 """
175
176         def getMinXY():
177                 """
178                 Get the x & y origin for the image. Image coordinates range from 0 to size-1.
179                 @returns: [x, y]
180                 @rtype: list of 2 ints
181                 """
182
183         def getXRep():
184                 """
185                 Get the number of repetitions in the x (horizontal) axis for this Image.
186                 This is for texture tiling.
187                 @rtype: int
188                 """
189
190         def getYRep():
191                 """
192                 Get the number of repetitions in the y (vertical) axis for this Image.
193                 This is for texture tiling.
194                 @rtype: int
195                 """
196
197         def getBindCode():
198                 """
199                 Get the Image's bindcode.  This is for texture loading using BGL calls.
200                 See, for example, L{BGL.glBindTexture} and L{glLoad}.
201                 @rtype: int
202                 """
203
204         def getStart():
205                 """
206                 Get the Image's start frame. Used for animated textures.
207                 @rtype: int
208                 """
209
210         def getEnd():
211                 """
212                 Get the Image's end frame. Used for animated textures.
213                 @rtype: int
214                 """
215
216         def getSpeed():
217                 """
218                 Get the Image's speed (fps). Used for animated textures.
219                 @rtype: int
220                 """
221
222         def reload():
223                 """
224                 Reloads this image from the filesystem.  If used within a loop you need to
225                 redraw the Window to see the change in the image, e.g. with
226                 Window.RedrawAll().
227                 @warn: if the image file is corrupt or still being written, it will be
228                         replaced by a blank image in Blender, but no error will be returned.
229                 @returns: None
230                 """
231
232         def glLoad():
233                 """
234                 Load this image's data into OpenGL texture memory, if it is not already
235                 loaded (image.bindcode is 0 if it is not loaded yet).
236                 @note: Usually you don't need to call this method.  It is only necessary
237                         if you want to draw textured objects in the Scripts window and the
238                         image's bind code is zero at that moment, otherwise Blender itself can
239                         take care of binding / unbinding textures.  Calling this method for an
240                         image with nonzero bind code simply returns the image's bind code value
241                         (see L{getBindCode}).
242                 @rtype: int
243                 @returns: the texture's bind code.
244                 """
245
246         def glFree():
247                 """
248                 Delete this image's data from OpenGL texture memory, only (the image itself
249                 is not removed from Blender's memory).  Internally, glDeleteTextures (see
250                 L{BGL.glDeleteTextures}) is used, but this method also updates Blender's
251                 Image object so that its bind code is set to 0.  See also L{Image.glLoad},
252                 L{Image.getBindCode}.
253                 """
254
255         def setName(name):
256                 """
257                 Set the name of this Image object.
258                 @type name: string
259                 @param name: The new name.
260                 """
261
262         def setFilename(name):
263                 """
264                 Change the filename of this Image object.
265                 @type name: string
266                 @param name: The new full filename.
267                 @warn: use this with caution and note that the filename is truncated if
268                         larger than 160 characters.
269                 """
270
271         def setXRep(xrep):
272                 """
273                 Texture tiling: set the number of x repetitions for this Image.
274                 @type xrep: int
275                 @param xrep: The new value in [1, 16].
276                 """
277
278         def setYRep(yrep):
279                 """
280                 Texture tiling: set the number of y repetitions for this Image.
281                 @type yrep: int
282                 @param yrep: The new value in [1, 16].
283                 """
284
285         def setStart(start):
286                 """
287                 Get the Image's start frame. Used for animated textures.
288                 @type start: int
289                 @param start: The new value in [0, 128].
290                 """
291
292         def setEnd(end):
293                 """
294                 Set the Image's end frame. Used for animated textures.
295                 @type end: int
296                 @param end: The new value in [0, 128].
297                 """
298
299         def setSpeed(speed):
300                 """
301                 Set the Image's speed (fps). Used for animated textures.
302                 @type speed: int
303                 @param speed: The new value in [1, 100].
304                 """
305
306         def setPixelF(x, y, (r, g, b,a )):
307                 """
308                 Set the the colors of the current pixel in the form [r,g,b,a].
309                 Color values must be floats in the range 0.0 - 1.0.
310                 Pixel coordinates are in the range from 0 to N-1.  See L{getMaxXY}
311                 @type x: int
312                 @type y: int
313                 @type r: float
314                 @type g: float
315                 @type b: float
316                 @type a: float
317                 @returns: nothing
318                 @rtype: none
319                 """
320                 
321         def setPixelI(x, y, (r, g, b, a)):
322                 """
323                 Set the the colors of the current pixel in the form [r,g,b,a].
324                 Color values must be ints in the range 0 - 255.
325                 Pixel coordinates are in the range from 0 to N-1.  See L{getMaxXY}
326                 @type x: int
327                 @type y: int
328                 @type r: int
329                 @type g: int
330                 @type b: int
331                 @type a: int
332                 @returns: nothing
333                 @rtype: none
334                 """
335                 
336         def save():
337                 """
338                 Saves the current image to L{filename}
339                 @note: Saving to a directory that doent exist will raise an error.
340                 @note: Saving a packed image will make a unique (numbered) name if the file alredy exists. Remove the file first to be sure it will not be renamed.
341                 @returns: None
342                 """
343         
344         def pack():
345                 """
346                 Packs the image into the current blend file.
347                 
348                 Since 2.44 new images without valid filenames can be packed.
349                 
350                 If the image is alredy packed, it will be repacked.
351                 
352                 @returns: nothing
353                 @rtype: none
354                 """
355
356         def unpack(mode):
357                 """
358                 Unpacks the image to the images filename.
359                 @param mode: One of the values in L{Blender.UnpackModes}.
360                 @note: An error will be raised if the image is not packed or the filename path does not exist.
361                 @returns: nothing
362                 @rtype: none
363                 @type mode: int
364                 """
365         def makeCurrent():
366                 """
367                 Set the currently displayed Image from Blenders UV/Image window.
368                 When multiple images are displayed, the last active UV/Image windows image is used.
369                 @warn: Deprecated, set bpy.data.images.active = image instead.
370                 @rtype: bool
371                 @return: True if the current image could be set, if no window was available, return False.
372                 """
373 import id_generics
374 Image.__doc__ += id_generics.attributes