=bmesh= merge from trunk at r36153
[blender.git] / source / gameengine / PyDoc / VideoTexture.py
1 # $Id$
2 """
3 The VideoTexture module allows you to manipulate textures during the game.
4
5 Several sources for texture are possible: video files, image files, 
6 video capture, memory buffer, camera render or a mix of that.
7
8 The video and image files can be loaded from the internet using an URL 
9 instead of a file name.
10
11 In addition, you can apply filters on the images before sending them to the GPU, allowing video effect: blue screen, 
12 color band, gray, normal map.
13
14 VideoTexture uses FFmpeg to load images and videos. All the formats and codecs
15 that FFmpeg supports are supported by VideoTexture, including but not limited to::
16
17         * AVI
18         * Ogg
19         * Xvid
20         * Theora
21         * dv1394 camera
22         * video4linux capture card (this includes many webcams)
23         * videoForWindows capture card (this includes many webcams)
24         * JPG 
25
26 The principle is simple: first you identify a texture on an existing object using 
27 the L{materialID} function, then you create a new texture with dynamic content
28 and swap the two textures in the GPU.
29
30 The GE is not aware of the substitution and continues to display the object as always, 
31 except that you are now in control of the texture.
32
33 When the texture object is deleted, the new texture is deleted and the old texture restored. 
34
35 Example::
36         import VideoTexture
37         import GameLogic
38
39         contr = GameLogic.getCurrentController()
40         obj = contr.owner
41         
42         # the creation of the texture must be done once: save the 
43         # texture object in an attribute of GameLogic module makes it persistent
44         if not hasattr(GameLogic, 'video'):
45         
46                 # identify a static texture by name
47                 matID = VideoTexture.materialID(obj, 'IMvideo.png')
48                 
49                 # create a dynamic texture that will replace the static texture
50                 GameLogic.video = VideoTexture.Texture(obj, matID)
51                 
52                 # define a source of image for the texture, here a movie
53                 movie = GameLogic.expandPath('//trailer_400p.ogg')
54                 GameLogic.video.source = VideoTexture.VideoFFmpeg(movie)
55                 GameLogic.video.source.scale = True
56                 
57                 # quick off the movie, but it wont play in the background
58                 GameLogic.video.source.play()   
59                 
60                 # you need to call this function every frame to ensure update of the texture.
61                 GameLogic.video.refresh(True)
62         
63
64 """
65 def getLastError():
66         """
67         Returns the description of the last error that occurred in a VideoTexture function.
68         
69         @rtype: string
70         """
71 def imageToArray(image,mode):
72         """
73         Returns a BGL.buffer corresponding to the current image stored in a texture source object
74
75         @param image: Image source object.
76         @type image: object of type L{VideoFFmpeg}, L{ImageFFmpeg}, L{ImageBuff}, L{ImageMix}, L{ImageRender}, L{ImageMirror} or L{ImageViewport}
77         @param mode: optional argument representing the pixel format. 
78                      You can use the characters R, G, B for the 3 color channels, A for the alpha channel, 
79                      0 to force a fixed 0 color channel and 1 to force a fixed 255 color channel.
80                      Example: "BGR" will return 3 bytes per pixel with the Blue, Green and Red channels in that order. \
81                               "RGB1" will return 4 bytes per pixel with the Red, Green, Blue channels in that order and the alpha channel forced to 255.
82                      The default mode is "RGBA".
83         @type mode: string
84         @rtype: BGL.buffer
85         @returns: object representing the image as one dimensional array of bytes of size (pixel_size*width*height), line by line starting from the bottom of the image. The pixel size and format is determined by the mode parameter.
86         """
87
88 def materialID(object,name):
89         """
90         Returns a numeric value that can be used in L{Texture} to create a dynamic texture.
91
92         The value corresponds to an internal material number that uses the texture identified
93         by name. name is a string representing a texture name with IM prefix if you want to
94         identify the texture directly.  This method works for basic tex face and for material,
95         provided the material has a texture channel using that particular texture in first
96         position of the texture stack.  name can also have MA prefix if you want to identify
97         the texture by material. In that case the material must have a texture channel in first
98         position.
99         
100         If the object has no material that matches name, it generates a runtime error. Use try/except to catch the exception.
101         
102         Ex: VideoTexture.materialID(obj, 'IMvideo.png')
103         
104         @param object: the game object that uses the texture you want to make dynamic
105         @type object: game object
106         @param name: name of the texture/material you want to make dynamic. 
107         @type name: string
108         @rtype: integer
109         """
110 def setLogFile(filename):
111         """
112         Sets the name of a text file in which runtime error messages will be written, in addition to the printing
113         of the messages on the Python console. Only the runtime errors specific to the VideoTexture module
114         are written in that file, ordinary runtime time errors are not written. 
115
116         @param filename: name of error log file
117         @type filename: string
118         @rtype: integer
119         """
120 def FilterBGR24():
121         """
122         Returns a new input filter object to be used with L{ImageBuff} object when the image passed 
123         to the ImageBuff.load() function has the 3-bytes pixel format BGR. 
124         
125         @rtype: object of type FilterBGR24
126         """
127 def FilterBlueScreen():
128         """
129         Does something
130         
131         @rtype: 
132         """
133 def FilterColor():
134         """
135         Does something
136         
137         @rtype: 
138         """
139 def FilterGray():
140         """
141         Does something
142         
143         @rtype: 
144         """
145 def FilterLevel():
146         """
147         Does something
148         
149         @rtype: 
150         """
151 def FilterNormal():
152         """
153         Does something
154         
155         @rtype: 
156         """
157 def FilterRGB24():
158         """
159         Returns a new input filter object to be used with L{ImageBuff} object when the image passed 
160         to the ImageBuff.load() function has the 3-bytes pixel format RBG.
161         
162         @rtype: object of type FilterRGB24
163         """
164 def FilterRGBA32():
165         """
166         Returns a new input filter object to be used with L{ImageBuff} object when the image passed 
167         to the ImageBuff.load() function has the 4-bytes pixel format RGBA.
168         
169         @rtype: object of type FilterRGBA32
170         """
171 def ImageBuff():
172         """
173         Does something
174         
175         @rtype: 
176         """
177 def ImageFFmpeg():
178         """
179         Does something
180         
181         @rtype: 
182         """
183 def ImageMirror():
184         """
185         Does something
186         
187         @rtype: 
188         """
189 def ImageMix():
190         """
191         Does something
192         
193         @rtype: 
194         """
195 def ImageRender():
196         """
197         Does something
198         
199         @rtype: 
200         """
201 def ImageViewport():
202         """
203         Does something
204         
205         @rtype: 
206         """
207 def Texture():
208         """
209         Does something
210         
211         @rtype: L{Texture}
212         """
213 def VideoFFmpeg():
214         """
215         Does something
216         
217         @rtype: 
218         """