Texture and Pixmap API Changes

Hi there,

i finished implementing the new imaging backend and reworked the Texture and Pixmap classes. From now on Textures and Pixmaps are instantiated directly. Here’s the constructors of Texture.

The first two constructors load a Texture from a file, the next two constructors load a Texture from a Pixmap. The fifth constructor creates an empty texture based on width/height/format. The last constructor is a way to implement your own managed texture loading. We still have the disctinction between managed and unmanaged Textures. Managed Textures will be reconstructed automatically in case of an OpenGL ES context loss (e.g. app is paused and resumed).

  • managed: Textures from files and TextureData
  • unmanaged: Textures from Pixmaps and width/height/format

The constructors with the mipmap parameter will tell the Texture to create a mipmap chain. When using OpenGL ES 1.x a mipmapped Texture must be square. It’s a limitation of OpenGL ES 1.x, nothing we can do about it.

You may have noticed that we also got rid of the hideously long parameter lists. We removed the filter and wrap parameters. By default the filters will be set to GL_NEAREST, and the wrap to GL_CLAMP_TO_EDGE. In case mipmap is set to true the minification filter will be set to TextureFilter.MipMap automatically. To change the filters or wraps use:

Textures aren’t alpha-premultiplied anymore either.

Pixmaps also got refactored. They are now based on Gdx2DPixmap, a class wrapping the native code responsible for image loading and manipulation. Here are the constructors. To construct a Pixmap you can use one of the following constructors:

The first constructor loads a Pixmap from a file. The file must be either a Jpeg, Png or Bmp. The second constructor creates an empty Pixmap based on width/height/format. Here’s the formats we support:

  • alpha: 8-bit per pixel, only encodes transparency.
  • luminance alpha: 16-bit per pixel, first byte in memory is luminance, next byte is alpha.
  • rgb565: 16-bit per pixel, stored in form of a machine byte order dependent short. Bits 0-4 encode blue, 5-10 encode green and 11-15 red
  • rgba4444: 16-bit per pixel, stored in form of a machine byte order dependent short. Bits 0-3 encode alpha, 4-7 blue, 8-11 green and 12-15 red
  • rgb888: 24-bit per pixel. red is stored in the first byte, then green then blue.
  • rgba8888: 32-bit per pixel. red is stored in the first byte, then green, blue and alpha

All the drawing operations like Pixmap.setPixel() or Pixmap.drawLine() are still there. E.g.

All the drawing methods also support blending which is on by default. You can change it via

Blending is a global state unlike color which is stored per Pixmap. Finally we added a few new methods to Pixmap:

The first method gives you direct access to the underlying pixels. This gives you the greatest possible freedom to do whatever you want with your image data. The second method is a new blitter that allows you to copy one portion of an image to a no necessarily equal sized area in another image. Blending applies here as well. If the destination region is not equal in size to the source region scaling and stretching is performed automatically. By default bilinear filtering is used, you can set the filter to nearest neighbour filtering as well with

This is also a global state like blending. Finally, you must dispose Pixmaps if no longer needed! Otherwise you’ll have memory leaks on the native heap!

The changes will go live in a few minutes. You will need to change how you instaniate Textures and Pixmaps, the rest stays the same. Just make sure to set whatever filters and wraps you need for a Texture explicitely as stated above. The defaults might not be what you want.

Finally, while i tested this quite a bit already i suspect there to be some dragons. If you find something using the latest nightlies please report back and attach a simple ApplicationListener for us to reproduce the issue.

One thought on “Texture and Pixmap API Changes

Leave a Reply

Your email address will not be published.