doc/python_api/rst/bge.texture.rst

   1
   2 Game Engine bge.texture Module
   3 ==============================
   4
   5 .. note::
   6    This documentation is still very weak, and needs some help! Right now they are mostly a collection
   7    of the docstrings found in the bge.texture source code + some random places filled with text.
   8
   9 *****
  10 Intro
  11 *****
  12
  13 The bge.texture module allows you to manipulate textures during the game.
  14
  15 Several sources for texture are possible: video files, image files, video capture, memory buffer, camera render or a mix of that.
  16
  17 The video and image files can be loaded from the internet using an URL instead of a file name.
  18
  19 In addition, you can apply filters on the images before sending them to the GPU, allowing video effect: blue screen, color band, gray, normal map.
  20
  21 bge.texture uses FFmpeg to load images and videos. All the formats and codecs that FFmpeg supports are supported by this module, including but not limited to::
  22
  23 * AVI
  24 * Ogg
  25 * Xvid
  26 * Theora
  27 * dv1394 camera
  28 * video4linux capture card (this includes many webcams)
  29 * videoForWindows capture card (this includes many webcams)
  30 * JPG
  31
  32 The principle is simple: first you identify a texture on an existing object using
  33 the :materialID: function, then you create a new texture with dynamic content
  34 and swap the two textures in the GPU.
  35
  36 The GE is not aware of the substitution and continues to display the object as always,
  37 except that you are now in control of the texture.
  38
  39 When the texture object is deleted, the new texture is deleted and the old texture restored.
  40
  41 .. module:: bge.texture
  42
  43 .. class:: VideoFFmpeg(file [, capture=-1, rate=25.0, width=0, height=0])
  44
  45    FFmpeg video source
  46
  47    .. attribute:: status
  48       video status
  49
  50    .. attribute::  range
  51       replay range
  52
  53    .. attribute:: repeat
  54       repeat count, -1 for infinite repeat
  55
  56       :type: int
  57
  58    .. attribute:: framerate
  59       frame rate
  60
  61       :type: float
  62
  63    .. attribute:: valid
  64       Tells if an image is available
  65
  66       :type: bool
  67
  68    .. attribute:: image
  69       image data
  70
  71    .. attribute:: size
  72       image size
  73
  74    .. attribute:: scale
  75       fast scale of image (near neighbour)
  76
  77    .. attribute:: flip
  78       flip image vertically
  79
  80    .. attribute:: filter
  81       pixel filter
  82
  83    .. attribute:: preseek
  84       number of frames of preseek
  85
  86       :type: int
  87
  88    .. attribute:: deinterlace
  89       deinterlace image
  90
  91       :type: bool
  92
  93    .. method:: play()
  94       Play (restart) video
  95
  96    .. method:: pause()
  97       pause video
  98
  99    .. method:: stop()
 100       stop video (play will replay it from start)
 101
 102    .. method:: refresh()
 103       Refresh video - get its status
 104
 105 .. class:: ImageFFmpeg(file)
 106
 107    FFmpeg image source
 108
 109    .. attribute:: status
 110       video status
 111
 112    .. attribute:: valid
 113       Tells if an image is available
 114
 115       :type: bool
 116
 117    .. attribute:: image
 118       image data
 119
 120    .. attribute:: size
 121       image size
 122
 123    .. attribute:: scale
 124       fast scale of image (near neighbour)
 125
 126    .. attribute:: flip
 127       flip image vertically
 128
 129    .. attribute:: filter
 130       pixel filter
 131
 132    .. method:: refresh()
 133       Refresh image, i.e. load it
 134
 135    .. method:: reload([newname])
 136       Reload image, i.e. reopen it
 137
 138 .. class:: ImageBuff()
 139
 140    Image source from image buffer
 141
 142    .. attribute:: filter
 143       pixel filter
 144
 145    .. attribute:: flip
 146       flip image vertically
 147
 148    .. attribute:: image
 149       image data
 150
 151    .. method:: load(imageBuffer, width, height)
 152       Load image from buffer
 153
 154    .. method:: plot(imageBuffer, width, height, positionX, positionY)
 155       update image buffer
 156
 157    .. attribute:: scale
 158       fast scale of image (near neighbour)
 159
 160    .. attribute:: size
 161       image size
 162
 163    .. attribute:: valid
 164       bool to tell if an image is available
 165
 166 .. class:: ImageMirror(scene)
 167
 168    Image source from mirror
 169
 170    .. attribute:: alpha
 171       use alpha in texture
 172
 173    .. attribute:: background
 174       background color
 175
 176    .. attribute:: capsize
 177       size of render area
 178
 179    .. attribute:: clip
 180       clipping distance
 181
 182    .. attribute:: filter
 183       pixel filter
 184
 185    .. attribute:: flip
 186       flip image vertically
 187
 188    .. attribute:: image
 189       image data
 190
 191    .. method:: refresh(imageMirror)
 192       Refresh image - invalidate its current content
 193
 194    .. attribute:: scale
 195       fast scale of image (near neighbour)
 196
 197    .. attribute:: size
 198       image size
 199
 200    .. attribute:: valid
 201       bool to tell if an image is available
 202
 203    .. attribute:: whole
 204       use whole viewport to render
 205
 206 .. class:: ImageMix()
 207
 208    Image mixer
 209
 210    .. attribute:: filter
 211       pixel filter
 212
 213    .. attribute:: flip
 214       flip image vertically
 215
 216    .. method:: getSource(imageMix)
 217       get image source
 218
 219    .. method:: getWeight(imageMix)
 220       get image source weight
 221
 222    .. attribute:: image
 223       image data
 224
 225    .. method:: refresh(imageMix)
 226       Refresh image - invalidate its current content
 227
 228    .. attribute:: scale
 229       fast scale of image (near neighbour)
 230
 231    .. method:: setSource(imageMix)
 232       set image source
 233
 234    .. method:: setWeight(imageMix)
 235       set image source weight
 236
 237    .. attribute:: valid
 238       bool to tell if an image is available
 239
 240 .. class:: ImageRender(scene, camera)
 241
 242    Image source from render
 243
 244    .. attribute:: alpha
 245       use alpha in texture
 246
 247    .. attribute:: background
 248       background color
 249
 250    .. attribute:: capsize
 251       size of render area
 252
 253    .. attribute:: filter
 254       pixel filter
 255
 256    .. attribute:: flip
 257       flip image vertically
 258
 259    .. attribute:: image
 260       image data
 261
 262    .. method:: refresh(imageRender)
 263       Refresh image - invalidate its current content
 264
 265    .. attribute:: scale
 266       fast scale of image (near neighbour)
 267
 268    .. attribute:: size
 269       image size
 270
 271    .. attribute:: valid
 272       bool to tell if an image is available
 273
 274    .. attribute:: whole
 275       use whole viewport to render
 276
 277 .. class:: ImageViewport()
 278
 279    Image source from viewport
 280
 281    .. attribute:: alpha
 282       use alpha in texture
 283
 284    .. attribute:: capsize
 285       size of viewport area being captured
 286
 287    .. attribute:: filter
 288       pixel filter
 289
 290    .. attribute:: flip
 291       flip image vertically
 292
 293    .. attribute:: image
 294       image data
 295
 296    .. attribute:: position
 297       upper left corner of captured area
 298
 299    .. method:: refresh(imageViewport)
 300       Refresh image - invalidate its current content
 301
 302    .. attribute:: scale
 303       fast scale of image (near neighbour)
 304
 305    .. attribute:: size
 306       image size
 307
 308    .. attribute:: valid
 309       bool to tell if an image is available
 310
 311    .. attribute:: whole
 312       use whole viewport to capture
 313
 314 .. class:: Texture(gameObj)
 315
 316    Texture objects
 317
 318    .. attribute:: bindId
 319       OpenGL Bind Name
 320
 321    .. method:: close(texture)
 322       Close dynamic texture and restore original
 323
 324    .. attribute:: mipmap
 325       mipmap texture
 326
 327    .. method:: refresh(texture)
 328       Refresh texture from source
 329
 330    .. attribute:: source
 331       source of texture
 332
 333 .. class:: FilterBGR24()
 334
 335    Source filter BGR24 objects
 336
 337 .. class:: FilterBlueScreen()
 338
 339    Filter for Blue Screen objects
 340
 341    .. attribute:: color
 342       blue screen color
 343
 344    .. attribute:: limits
 345       blue screen color limits
 346
 347    .. attribute:: previous
 348       previous pixel filter
 349
 350 .. class:: FilterColor()
 351
 352    Filter for color calculations
 353
 354    .. attribute:: matrix
 355       matrix [4][5] for color calculation
 356
 357    .. attribute:: previous
 358       previous pixel filter
 359
 360 .. class:: FilterGray()
 361
 362    Filter for gray scale effect
 363
 364    .. attribute:: previous
 365       previous pixel filter
 366
 367 .. class:: FilterLevel()
 368
 369    Filter for levels calculations
 370
 371    .. attribute:: levels
 372       levels matrix [4] (min, max)
 373
 374    .. attribute:: previous
 375       previous pixel filter
 376
 377 .. class:: FilterNormal()
 378
 379    Filter for Blue Screen objects
 380
 381    .. attribute:: colorIdx
 382       index of color used to calculate normal (0 - red, 1 - green, 2 - blue)
 383
 384    .. attribute:: depth
 385       depth of relief
 386
 387    .. attribute:: previous
 388       previous pixel filter
 389
 390 .. class:: FilterRGB24()
 391
 392    Returns a new input filter object to be used with :class:`ImageBuff` object when the image passed
 393    to the ImageBuff.load() function has the 3-bytes pixel format BGR.
 394
 395 .. class:: FilterRGBA32()
 396
 397    Source filter RGBA32 objects
 398
 399 .. function:: getLastError()
 400    Last error that occurred in a bge.texture function.
 401
 402    :return: the description of the last error occurred in a bge.texture function.
 403    :rtype: string
 404
 405 .. function:: imageToArray(image,mode)
 406    Returns a :class:`~bgl.buffer` corresponding to the current image stored in a texture source object.
 407
 408    :arg image: Image source object.
 409    :type image: object of type :class:`VideoFFmpeg`, :class:`ImageFFmpeg`, :class:`ImageBuff`, :class:`ImageMix`, :class:`ImageRender`, :class:`ImageMirror` or :class:`ImageViewport`
 410    :arg mode: optional argument representing the pixel format.
 411       You can use the characters R, G, B for the 3 color channels, A for the alpha channel,
 412       0 to force a fixed 0 color channel and 1 to force a fixed 255 color channel.
 413       Example: "BGR" will return 3 bytes per pixel with the Blue, Green and Red channels in that order.
 414       "RGB1" will return 4 bytes per pixel with the Red, Green, Blue channels in that order and the alpha channel forced to 255.
 415       The default mode is "RGBA".
 416
 417    :type mode: string
 418    :rtype: :class:`~bgl.buffer`
 419    :return: A object representing the image as one dimensional array of bytes of size (pixel_size*width*height),
 420       line by line starting from the bottom of the image. The pixel size and format is determined by the mode
 421       parameter.
 422
 423 .. function materialID(object,name)
 424    Returns a numeric value that can be used in :class:`Texture` to create a dynamic texture.
 425
 426    The value corresponds to an internal material number that uses the texture identified
 427    by name. name is a string representing a texture name with IM prefix if you want to
 428    identify the texture directly.    This method works for basic tex face and for material,
 429    provided the material has a texture channel using that particular texture in first
 430    position of the texture stack.    name can also have MA prefix if you want to identify
 431    the texture by material. In that case the material must have a texture channel in first
 432    position.
 433
 434    If the object has no material that matches name, it generates a runtime error. Use try/except to catch the exception.
 435
 436    Ex: bge.texture.materialID(obj, 'IMvideo.png')
 437
 438    :arg object: the game object that uses the texture you want to make dynamic
 439    :type object: game object
 440    :arg name: name of the texture/material you want to make dynamic.
 441    :type name: string
 442    :rtype: integer
 443
 444 .. function setLogFile(filename)
 445    Sets the name of a text file in which runtime error messages will be written, in addition to the printing
 446    of the messages on the Python console. Only the runtime errors specific to the VideoTexture module
 447    are written in that file, ordinary runtime time errors are not written.
 448
 449    :arg filename: name of error log file
 450    :type filename: string
 451    :rtype: integer