From 4cfa8bbf2f8b6859dc2ae4468153ac839493689e Mon Sep 17 00:00:00 2001 From: Mathieu Virbel Date: Mon, 6 Jun 2011 10:50:35 +0200 Subject: [PATCH] texture: add proper documentation on texture + colorfmt parameter in Texture --- kivy/graphics/texture.pyx | 126 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 122 insertions(+), 4 deletions(-) diff --git a/kivy/graphics/texture.pyx b/kivy/graphics/texture.pyx index 91e10022a..01e7dc331 100644 --- a/kivy/graphics/texture.pyx +++ b/kivy/graphics/texture.pyx @@ -1,11 +1,121 @@ #cython: embedsignature=True ''' -Texture management -================== +Texture +======= + +:class:`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 +:func:`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 (:data:`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 +:data:`kivy.graphics.VertexIntruction.texture` parameter. If you want to use +your texture in kv lang, you can save it in an +:class:`~kivy.properties.ObjectProperty` inside your widget. + + +Blitting custom data +-------------------- + +You can create your own data and blit it on the texture using +:func:`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 +------------ + +.. versionadded:: 1.0.7 + + If hardware can support NPOT, no POT are created. + +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 :func:`Texture.create` will +return a :class:`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) -OpenGL texture can be a pain to manage ourself, except if you know perfectly all -the OpenGL API :). ''' __all__ = ('Texture', 'TextureRegion') @@ -536,6 +646,14 @@ cdef class Texture: glTexParameteri(self.target, GL_TEXTURE_WRAP_T, _value) self._wrap = x + property colorfmt: + '''Return the color format used in this texture. + + .. versionadded:: 1.0.7 + ''' + def __get__(self): + return self._colorfmt + property min_filter: '''Get/set the min filter texture. Available values: