OpenGL::Sandbox::Texture - Wrapper object for OpenGL texture


version 0.04



Path from which image data will be loaded. If not set, the texture will not have any default image data loaded.


A method name or coderef of your choice for lazy-loading the image data. If not set, the loader is determined from the "filename" and if that is not set, nothing gets loaded on creation of the texture id tx_id.

Gets executed as $tex->$loader($filename).


Boolean; whether any image data has been loaded yet. This is not automatically aware of data you load yourself via calls to glTexImage or glTexSubImage.


Original width of the texture before it might have been rescaled to a square power of two.


Original height of the texture before it might have been rescaled to a square power of two.


Lazy-built OpenGL texture ID (integer). Triggers "load" if image is not yet loaded.


Check this to find out whether tx_id has been initialized.


Width of texture, in texels.


Height of texture, in texels. Currently will always equal width.


If texture is loaded as a square power-of-two (currently all are) then this returns the dimension of the texture. This can differ from width/height in the event that you configured those with the logical dimensions of the image. If texture was loaded as a rectangular texture, this is undef.


Boolean of whether the texture contains an alpha channel.


Boolean, whether texture has (or should have) mipmaps generated for it. When loading any "simple" image format, this setting controls whether mipmaps will be automatically generated.


Value for GL_TEXTURE_MIN_FILTER. Setting does not take effect until "loaded", but after that a change to this attribute takes effect immediately causing the texture to be bound.


Value for GL_TEXTURE_MAX_FILTER. See notes on "min_filter".


Value for GL_TEXTURE_WRAP_S. See notes on "min_filter".


Value for GL_TEXTURE_WRAP_T. See notes on "min_filter".



  $tex->bind( $target );

Make this image the current texture for OpenGL's $target, with the default of GL_TEXTURE_2D. If "tx_id" does not exist yet, it gets created. If this texture has a "loader" or "filename" defined and has not yet been "loaded", this automatically calls "load".

Returns $self for convenient chaining.



Load image data from a file into OpenGL. This does not happen when the object is first constructed, in case the OpenGL context hasn't been initialized yet. It automatically happens when "bind" is called for the first time.

Calls $self->loader->($self, $self->filename). "tx_id" will be a valid texture id after this (assuming the loader doesn't die).

Returns $self for convenient chaining.


Load image data from a file which is nothing more than raw RGB or RGBA pixels in a power-of-two dimension suitable for directly loading into OpenGL. The dimensions and presence of alpha channel are derived mathematically from the file size. The data is directly mmap'd so no copying is performed before handing the pointer to OpenGL.


Same as rgb, except the source data has the red and blue bytes swapped.


Load image data from a PNG file. The file is read and decoded, and if it is a square power of two dimension, it is loaded directly. If it is rectangular, it gets stretched out to the next power of two square, using libswscale.

This library currently has no provision for the OpenGL "rectangular texture" extension that allows for actual rectangular images and positive integer texture coordinates. That could be a useful addition.

TODO: load_ktx

OpenGL has its own image file format designed to directly handle all the various things you might want to load into a texture. Integrating libktx is on my list.


  $tex->render( %opts );

Render the texture as a plain rectangle with optional coordinate/size modifications. Implies a call to /bind which might also trigger "load".

Assumes you have already enabled GL_TEXTURE_2D, and that you are not using shaders. (future versions might include a shader-compatible implementation)

x, y

Use specified origin point. Uses (0,0) if these are not provided.

w, h

Use specified width and/or height. If undefined, defaults to pixel dimensions of the source image, unless only one is specified then it calculates the other using the aspect ratio. If source dimensions are not set, it uses the actual texture dimensions. These may or might not make sense for your current OpenGL coordinate space.


Multiply width and height by this number.


Center the image on the origin, instead of using the origin as the lower-left corner.

s, t

Starting offset texture coordinates for the lower-left corner.

s_rep, t_rep

The number of repititions of the texture to use across the face of the described rectangle. These won't give the desired result if you set the wrap mode of the texture to GL_CLAMP.


Like "render" but skips the call to "bind", for when you know that it is already the current texture.



  convert_png("foo.png", "foo.rgb");

Read a .png file and write an .rgb (or .bgr) file. The .png will be scaled to a square power of 2 if it is not already. The pixel format of the PNG must be RGB or RGBA. This does not require an OpenGL context.


Michael Conrad <>


This software is copyright (c) 2019 by Michael Conrad.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.