4ebd6721c545d3920a0064e0323907d4f07e4a11
[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 getPixel(x, y):
98     """
99         Get the the colors of the current pixel in the form [r,g,b,a].
100         Pixel coordinates are in the range from 0 to N-1.  See L{getMaxXY}
101         @returns: [ r, g, b, a]
102         @rtype: list of 4 floats
103         @type x: int
104         @type y: int
105         @param x:  the x coordinate of pixel.
106         @param y:  the y coordinate of pixel.  
107     """
108
109   def getMaxXY():
110     """
111     Get the  x & y size for the image.  Image coordinates range from 0 to size-1.
112     @returns: [x, y]
113     @rtype: list of 2 ints
114     """
115
116   def getXRep():
117     """
118     Get the number of repetitions in the x (horizontal) axis for this Image.
119     This is for texture tiling.
120     @rtype: int
121     """
122
123   def getYRep():
124     """
125     Get the number of repetitions in the y (vertical) axis for this Image.
126     This is for texture tiling.
127     @rtype: int
128     """
129
130   def getBindCode():
131     """
132     Get the Image's bindcode.  This is for texture loading using BGL calls.
133     See, for example, L{BGL.glBindTexture} and L{glLoad}.
134     @rtype: int
135     """
136
137   def reload():
138     """
139     Reloads this image from the filesystem.  If used within a loop you need to
140     redraw the Window to see the change in the image, e.g. with
141     Window.RedrawAll().
142     @warn: if the image file is corrupt or still being written, it will be
143        replaced by a blank image in Blender, but no error will be returned.
144     @returns: None
145     """
146
147   def glLoad():
148     """
149     Load this image's data into OpenGL texture memory, if it is not already
150     loaded (image.bindcode is 0 if it is not loaded yet).
151     @note: Usually you don't need to call this method.  It is only necessary
152        if you want to draw textured objects in the Scripts window and the
153        image's bind code is zero at that moment, otherwise Blender itself can
154        take care of binding / unbinding textures.  Calling this method for an
155        image with nonzero bind code simply returns the image's bind code value
156        (see L{getBindCode}).
157     @rtype: int
158     @returns: the texture's bind code.
159     """
160
161   def glFree():
162     """
163     Delete this image's data from OpenGL texture memory, only (the image itself
164     is not removed from Blender's memory).  Internally, glDeleteTextures (see
165     L{BGL.glDeleteTextures}) is used, but this method also updates Blender's
166     Image object so that its bind code is set to 0.  See also L{Image.glLoad},
167     L{Image.getBindCode}.
168     """
169
170   def setName(name):
171     """
172     Set the name of this Image object.
173     @type name: string
174     @param name: The new name.
175     """
176
177   def setFilename(name):
178     """
179     Change the filename of this Image object.
180     @type name: string
181     @param name: The new full filename.
182     @warn: use this with caution and note that the filename is truncated if
183        larger than 160 characters.
184     """
185
186   def setXRep(xrep):
187     """
188     Texture tiling: set the number of x repetitions for this Image.
189     @type xrep: int
190     @param xrep: The new value in [1, 16].
191     """
192
193   def setYRep(yrep):
194     """
195     Texture tiling: set the number of y repetitions for this Image.
196     @type yrep: int
197     @param yrep: The new value in [1, 16].
198     """