Rename Image.getPixel() to .getPixelF() as per discussion
[blender-staging.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.setFilename}.
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
25 def Load (filename):
26   """
27   Load the image called 'filename' into an Image object.
28   @type filename: string
29   @param filename: The full path to the image file.
30   @rtype:  Blender Image
31   @return: A Blender Image object with the data from I{filename}.
32   """
33
34 def New (name):
35   """
36   Create a new Image object (not implemented yet!).
37   @type name: string
38   @param name: The name of the new Image object.
39   @rtype: Blender Image
40   @return: A new Blender Image object.
41   @warn: This function wasn't implemented yet.  It simply returns None.
42   """
43
44 def Get (name = None):
45   """
46   Get the Image object(s) from Blender.
47   @type name: string
48   @param name: The name of the Image object.
49   @rtype: Blender Image or a list of Blender Images
50   @return: It depends on the I{name} parameter:
51       - (name): The Image object called I{name}, None if not found;
52       - (): A list with all Image objects in the current scene.
53   """
54
55
56 class Image:
57   """
58   The Image object
59   ================
60     This object gives access to Images in Blender.
61   @cvar name: The name of this Image object.
62   @cvar filename: The filename (path) to the image file loaded into this Image
63      object.
64   @cvar size: The [width, height] dimensions of the image (in pixels).
65   @cvar depth: The pixel depth of the image.
66   @cvar xrep: Texture tiling: the number of repetitions in the x (horizontal)
67      axis.
68   @cvar yrep: Texture tiling: the number of repetitions in the y (vertical)
69      axis.
70   @cvar bindcode: Texture's bind code (readonly).
71   """
72
73   def getName():
74     """
75     Get the name of this Image object.
76     @rtype: string
77     """
78
79   def getFilename():
80     """
81     Get the filename of the image file loaded into this Image object.
82     @rtype: string
83     """
84
85   def getSize():
86     """
87     Get the [width, height] dimensions (in pixels) of this image.
88     @rtype: list of 2 ints
89     """
90
91   def getDepth():
92     """
93     Get the pixel depth of this image.
94     @rtype: int
95     """
96
97   def getPixelF(x, y):
98     """
99         Get the the colors of the current pixel in the form [r,g,b,a].
100         Returned values are floats normalized to 0.0 - 1.0.
101         Pixel coordinates are in the range from 0 to N-1.  See L{getMaxXY}
102         @returns: [ r, g, b, a]
103         @rtype: list of 4 floats
104         @type x: int
105         @type y: int
106         @param x:  the x coordinate of pixel.
107         @param y:  the y coordinate of pixel.  
108     """
109
110   def getMaxXY():
111     """
112     Get the  x & y size for the image.  Image coordinates range from 0 to size-1.
113     @returns: [x, y]
114     @rtype: list of 2 ints
115     """
116
117   def getXRep():
118     """
119     Get the number of repetitions in the x (horizontal) axis for this Image.
120     This is for texture tiling.
121     @rtype: int
122     """
123
124   def getYRep():
125     """
126     Get the number of repetitions in the y (vertical) axis for this Image.
127     This is for texture tiling.
128     @rtype: int
129     """
130
131   def getBindCode():
132     """
133     Get the Image's bindcode.  This is for texture loading using BGL calls.
134     See, for example, L{BGL.glBindTexture} and L{glLoad}.
135     @rtype: int
136     """
137
138   def reload():
139     """
140     Reloads this image from the filesystem.  If used within a loop you need to
141     redraw the Window to see the change in the image, e.g. with
142     Window.RedrawAll().
143     @warn: if the image file is corrupt or still being written, it will be
144        replaced by a blank image in Blender, but no error will be returned.
145     @returns: None
146     """
147
148   def glLoad():
149     """
150     Load this image's data into OpenGL texture memory, if it is not already
151     loaded (image.bindcode is 0 if it is not loaded yet).
152     @note: Usually you don't need to call this method.  It is only necessary
153        if you want to draw textured objects in the Scripts window and the
154        image's bind code is zero at that moment, otherwise Blender itself can
155        take care of binding / unbinding textures.  Calling this method for an
156        image with nonzero bind code simply returns the image's bind code value
157        (see L{getBindCode}).
158     @rtype: int
159     @returns: the texture's bind code.
160     """
161
162   def glFree():
163     """
164     Delete this image's data from OpenGL texture memory, only (the image itself
165     is not removed from Blender's memory).  Internally, glDeleteTextures (see
166     L{BGL.glDeleteTextures}) is used, but this method also updates Blender's
167     Image object so that its bind code is set to 0.  See also L{Image.glLoad},
168     L{Image.getBindCode}.
169     """
170
171   def setName(name):
172     """
173     Set the name of this Image object.
174     @type name: string
175     @param name: The new name.
176     """
177
178   def setFilename(name):
179     """
180     Change the filename of this Image object.
181     @type name: string
182     @param name: The new full filename.
183     @warn: use this with caution and note that the filename is truncated if
184        larger than 160 characters.
185     """
186
187   def setXRep(xrep):
188     """
189     Texture tiling: set the number of x repetitions for this Image.
190     @type xrep: int
191     @param xrep: The new value in [1, 16].
192     """
193
194   def setYRep(yrep):
195     """
196     Texture tiling: set the number of y repetitions for this Image.
197     @type yrep: int
198     @param yrep: The new value in [1, 16].
199     """