Table Of Contents
Texture¶
Changed in version 1.6.0: Added support for paletted texture on OES: ‘palette4_rgb8’, ‘palette4_rgba8’, ‘palette4_r5_g6_b5’, ‘palette4_rgba4’, ‘palette4_rgb5_a1’, ‘palette8_rgb8’, ‘palette8_rgba8’, ‘palette8_r5_g6_b5’, ‘palette8_rgba4’, ‘palette8_rgb5_a1’
Texture is a class to handle OpenGL texture. Depending of the hardware, some OpenGL capabilities might not be available (BGRA support, NPOT support, etc.)
You cannot instanciate the class yourself. You must use the function Texture.create() to create a new texture:
texture = Texture.create(size=(640, 480))
When you are creating a texture, you must be aware of the default color format and buffer format:
- the color/pixel format (Texture.colorfmt), that can be one of ‘rgb’, ‘rgba’, ‘luminance’, ‘luminance_alpha’, ‘bgr’, ‘bgra’. The default value is ‘rgb’
- the buffer format is how a color component is stored into memory. This can be one of ‘ubyte’, ‘ushort’, ‘uint’, ‘byte’, ‘short’, ‘int’, ‘float’. The default value and the most commonly used is ‘ubyte’.
So, if you want to create an RGBA texture:
texture = Texture.create(size=(640, 480), colorfmt='rgba')
You can use your texture in almost all vertex instructions with the kivy.graphics.VertexIntruction.texture parameter. If you want to use your texture in kv lang, you can save it in an ObjectProperty inside your widget.
Blitting custom data¶
You can create your own data and blit it on the texture using Texture.blit_data():
# create a 64x64 texture, default to rgb / ubyte
texture = Texture.create(size=(64, 64))
# create 64x64 rgb tab, and fill with value from 0 to 255
# we'll have a gradient from black to white
size = 64 * 64 * 3
buf = [int(x * 255 / size) for x in xrange(size)]
# then, convert the array to a ubyte string
buf = ''.join(map(chr, buf))
# then blit the buffer
texture.blit_buffer(buf, colorfmt='rgb', bufferfmt='ubyte')
# that's all ! you can use it in your graphics now :)
# if self is a widget, you can do that
with self.canvas:
Rectangle(texture=texture, pos=self.pos, size=(64, 64))
BGR/BGRA support¶
The first time you’ll try to create a BGR or BGRA texture, we are checking if your hardware support BGR / BGRA texture by checking the extension ‘GL_EXT_bgra’.
If the extension is not found, a conversion to RGB / RGBA will be done in software.
NPOT texture¶
New in version 1.0.7.
As OpenGL documentation said, a texture must be power-of-two sized. That’s mean your width and height can be one of 64, 32, 256... but not 3, 68, 42. NPOT mean non-power-of-two. OpenGL ES 2 support NPOT texture natively, but with some drawbacks. Another type of NPOT texture are also called rectangle texture. POT, NPOT and texture have their own pro/cons.
Features | POT | NPOT | Rectangle |
OpenGL Target | GL_TEXTURE_2D | GL_TEXTURE_2D | GL_TEXTURE_RECTANGLE_(NV|ARB|EXT) |
Texture coords | 0-1 range | 0-1 range | width-height range |
Mipmapping | Supported | Partially | No |
Wrap mode | Supported | Supported | No |
If you are creating a NPOT texture, we first are checking if your hardware is capable of it by checking the extensions GL_ARB_texture_non_power_of_two or OES_texture_npot. If none of theses are availables, we are creating the nearest POT texture that can contain your NPOT texture. The Texture.create() will return a TextureRegion instead.
Texture atlas¶
We are calling texture atlas a texture that contain many images in it. If you want to seperate the original texture into many single one, you don’t need to. You can get a region of the original texture. That will return you the original texture with custom texture coordinates:
# for example, load a 128x128 image that contain 4 64x64 images
from kivy.core.image import Image
texture = Image('mycombinedimage.png').texture
bottomleft = texture.get_region(0, 0, 64, 64)
bottomright = texture.get_region(0, 64, 64, 64)
topleft = texture.get_region(0, 64, 64, 64)
topright = texture.get_region(64, 64, 64, 64)
Mipmapping¶
New in version 1.0.7.
Mipmapping is an OpenGL technique for enhancing the rendering of large texture to small surface. Without mipmapping, you might seen pixels when you are rendering to small surface. The idea is to precalculate subtexture and apply some image filter, as linear filter. Then, when you rendering a small surface, instead of using the biggest texture, it will use a lower filtered texture. The result can look better with that way.
To make that happen, you need to specify mipmap=True when you’re creating a texture. Some widget already give you the possibility to create mipmapped texture like Label or Image.
From the OpenGL Wiki : “So a 64x16 2D texture can have 5 mip-maps: 32x8, 16x4, 8x2, 4x1, 2x1, and 1x1”. Check http://www.opengl.org/wiki/Texture for more information.
Note
As the table in previous section said, if your texture is NPOT, we are actually creating the nearest POT texture and generate mipmap on it. This might change in the future.
Reloading the Texture¶
New in version 1.2.0.
If the OpenGL context is lost, the Texture must be reloaded. Texture having a source are automatically reloaded without any help. But generated textures must be reloaded by the user.
Use the Texture.add_reload_observer() to add a reloading function that will be automatically called when needed:
def __init__(self, **kwargs):
super(...).__init__(**kwargs)
self.texture = Texture.create(size=(512, 512), colorfmt='RGB',
bufferfmt='ubyte')
self.texture.add_reload_observer(self.populate_texture)
# and load the data now.
self.cbuffer = '
- class kivy.graphics.texture.Texture¶
Bases: object
Handle a OpenGL texture. This class can be used to create simple texture or complex texture based on ImageData.
- add_reload_observer()¶
Add a callback to be called after the whole graphics context have been reloaded. This is where you can reupload your custom data in GPU.
New in version 1.2.0.
Parameters : - callback: func(context) -> return None
The first parameter will be the context itself
- ask_update()¶
Indicate that the content of the texture should be updated, and the callback function need to be called when the texture will be really used.
- bind()¶
Bind the texture to current opengl state
- blit_buffer()¶
Blit a buffer into a texture.
New in version 1.0.7: added mipmap_level + mipmap_generation
Parameters : - pbuffer : str
Image data
- size : tuple, default to texture size
Size of the image (width, height)
- colorfmt : str, default to ‘rgb’
Image format, can be one of ‘rgb’, ‘rgba’, ‘bgr’, ‘bgra’, ‘luminance’, ‘luminance_alpha’
- pos : tuple, default to (0, 0)
Position to blit in the texture
- bufferfmt : str, default to ‘ubyte’
Type of the data buffer, can be one of ‘ubyte’, ‘ushort’, ‘uint’, ‘byte’, ‘short’, ‘int’, ‘float’
- mipmap_level: int, default to 0
Indicate which mipmap level we are going to update
- mipmap_generation: bool, default to False
Indicate if we need to regenerate mipmap from level 0
- blit_data()¶
Replace a whole texture with a image data
- bufferfmt¶
Return the buffer format used in this texture. (readonly)
New in version 1.2.0.
- colorfmt¶
Return the color format used in this texture. (readonly)
New in version 1.0.7.
- create()¶
Create a texture based on size.
Parameters : - size: tuple, default to (128, 128)
Size of the texture
- colorfmt: str, default to ‘rgba’
Internal color format of the texture. Can be ‘rgba’ or ‘rgb’, ‘luminance’, ‘luminance_alpha’
- bufferfmt: str, default to ‘ubyte’
Internal buffer format of the texture. Can be ‘ubyte’, ‘ushort’, ‘uint’, ‘bute’, ‘short’, ‘int’, ‘float’
- mipmap: bool, default to False
If True, it will automatically generate mipmap texture.
- callback: callable(), default to False
If a function is provided, it will be called when data will be needed in the texture.
Changed in version 1.7.0: callback has been added
- create_from_data()¶
Create a texture from an ImageData class
- flip_vertical()¶
Flip tex_coords for vertical displaying
- get_region()¶
Return a part of the texture defined by the rectangle arguments (x, y, width, height). Returns a TextureRegion instance.
- height¶
Return the height of the texture (readonly)
- id¶
Return the OpenGL ID of the texture (readonly)
- mag_filter¶
Get/set the mag filter texture. Available values:
- linear
- nearest
Check opengl documentation for more information about the behavior of theses values : http://www.khronos.org/opengles/sdk/docs/man/xhtml/glTexParameter.xml.
- min_filter¶
Get/set the min filter texture. Available values:
- linear
- nearest
- linear_mipmap_linear
- linear_mipmap_nearest
- nearest_mipmap_nearest
- nearest_mipmap_linear
Check opengl documentation for more information about the behavior of theses values : http://www.khronos.org/opengles/sdk/docs/man/xhtml/glTexParameter.xml.
- mipmap¶
Return True if the texture have mipmap enabled (readonly)
- pixels¶
Get the pixels texture, in RGBA format only, unsigned byte.
New in version 1.7.0.
- remove_reload_observer()¶
Remove a callback from the observer list, previously added by add_reload_observer().
New in version 1.2.0.
- save()¶
Save the texture content into a file. Check kivy.core.image.Image.save() for more information about the usage.
New in version 1.7.0.
- size¶
Return the (width, height) of the texture (readonly)
- target¶
Return the OpenGL target of the texture (readonly)
- tex_coords¶
Return the list of tex_coords (opengl)
- uvpos¶
Get/set the UV position inside texture
- uvsize¶
Get/set the UV size inside texture.
Warning
The size can be negative is the texture is flipped.
- width¶
Return the width of the texture (readonly)
- wrap¶
Get/set the wrap texture. Available values:
- repeat
- mirrored_repeat
- clamp_to_edge
Check opengl documentation for more information about the behavior of theses values : http://www.khronos.org/opengles/sdk/docs/man/xhtml/glTexParameter.xml.
- class kivy.graphics.texture.TextureRegion¶
Bases: kivy.graphics.texture.Texture
Handle a region of a Texture class. Useful for non power-of-2 texture handling.