Unofficial OpenGL Software Development Kit: Texture Creation

Unofficial OpenGL Software Development Kit 0.5.0

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Classes | Enumerations | Functions
Texture Creation
GL Image

##

Functions to build textures from ImageSet objects.

Most of GL Image's Almost all of these functions do not require GL Load to be initialized. Image loading and data storage/manipulation don't interact with OpenGL. However, these functions build OpenGL textures from OpenGL. Therefore, most of them interact with the OpenGL context, so they require that GL Load has been properly initialized.

The important function of interest is glimg::CreateTexture; this takes an ImageSet and generates an OpenGL texture object. There is an overload that can take a pre-created OpenGL texture object as well; you should not have used that texture object before.

There are also query functions that convert an ImageFormat into information that you can use to manually upload parts of an ImageSet. glimg::GetInternalFormat takes an ImageFormat and returns the corresponding OpenGL internal format that you should use in OpenGL texture storage creation calls.

glimg::GetUploadFormatType returns an object that can be used to supply the pixel transfer parameters (the second and third to last parameters to `glTex(Sub)Image`). If you are uploading a compressed texture, you can just use SingleImage::GetImageByteSize to get its size.

There are a number of flags that the user can provide which affect the selection of the OpenGL parameters.

## Classes

struct | glimg::OpenGLPixelTransferParams
| Contains the pixel transfer parameters for OpenGL texture upload functions. More...

## Enumerations

enum

glimg::ForcedConvertFlags {
glimg::FORCE_SRGB_COLORSPACE_FMT = 0x0001, glimg::FORCE_BC1_ALPHA_FMT = 0x0002, glimg::FORCE_LUMINANCE_FMT = 0x0008, glimg::FORCE_INTEGRAL_FMT = 0x0020,
glimg::FORCE_SIGNED_FMT = 0x0040, glimg::FORCE_COLOR_RENDERABLE_FMT = 0x0080, glimg::FORCE_ARRAY_TEXTURE = 0x0004, glimg::USE_TEXTURE_STORAGE = 0x0100,
glimg::FORCE_TEXTURE_STORAGE = 0x0200, glimg::USE_DSA = 0x0400, glimg::FORCE_DSA = 0x0800
}

| Control flags for texture conversion processes. More...

## Functions

unsigned int | glimg::GetInternalFormat (const ImageFormat &format, unsigned int forceConvertBits)
| Retrieves the OpenGL internal format for the given image format and bits. More...
OpenGLPixelTransferParams | glimg::GetUploadFormatType (const ImageFormat &format, unsigned int forceConvertBits)
| Retrieves the pixel transfer parameters for the given image format. More...
unsigned int | glimg::GetTextureType (const ImageSet *pImage, unsigned int forceConvertBits)
| Retrieves the texture type for the given ImageSet. More...
unsigned int | glimg::CreateTexture (const ImageSet *pImage, unsigned int forceConvertBits)
| Creates a texture object from the given ImageSet, with flags. More...
void | glimg::CreateTexture (unsigned int textureName, const ImageSet *pImage, unsigned int forceConvertBits)
| As CreateTexture(const ImageSet *, unsigned int), but with a texture object provided by the user. More...

## Enumeration Type Documentation

enum glimg::ForcedConvertFlags

Control flags for texture conversion processes.

These flags allow the user to alter the process used to select image formats and upload texture data. The enumerators that end in "FMT" affect how the format is chosen, while the ones ending in "TEX" affect the texture choice.

Todo:

  Finish implementing color renderable forcing.

  Implement the forcing of required formats.

Enumerator
FORCE_SRGB_COLORSPACE_FMT | When possible, will force the format to use the sRGB colorspace. Does not cause erroring for formats that can't be sRGB, unless your GL implementation doesn't support sRGB.
FORCE_BC1_ALPHA_FMT | When used with a BC1 texture, will force the texture to have an alpha. Ignored otherwise.
FORCE_LUMINANCE_FMT | Red and RG textures will become luminance and luminance/alpha textures in all cases. Exceptions will be thrown if the GL implementation does not support those luminance/alpha formats (ie: is core).
FORCE_INTEGRAL_FMT | Image formats that contain normalized integers will be uploaded as non-normalized integers. Ignored for floating-point or compressed formats.
FORCE_SIGNED_FMT | Image formats that contain unsigned integers will be uploaded as signed integers. Ignored if the format is not an integer/integral format, or if it isn't BC4 or BC5 compressed.
FORCE_COLOR_RENDERABLE_FMT | NOT YET SUPPORTED! Will force the use of formats that are required to be valid render targets. This will add components if necessary, but it will throw if conversion would require fundamentally changing the basic format (from signed to unsigned, compressed textures, etc).
FORCE_ARRAY_TEXTURE | NOT YET SUPPORTED! The texture will be an array texture even if the depth is not present. Ignored for formats that can't be arrays. Will throw if array textures of that type are not supported (ie: cubemap arrays, 2D arrays for lesser hardware, etc).
USE_TEXTURE_STORAGE | If ARB_texture_storage or GL 4.2 is available, then texture storage functions will be used to create the textures. Otherwise regular glTex* functions will be used.
FORCE_TEXTURE_STORAGE | If ARB_texture_storage or GL 4.2 is available, then texture storage functions will be used to create the textures. Otherwise, an exception will be thrown.
USE_DSA | If EXT_direct_state_access is available, then DSA functions will be used to create the texture. Otherwise, regular ones will be used.
FORCE_DSA | If EXT_direct_state_access is available, then DSA functions will be used to create the texture. Otherwise, an exception will be thrown.

## Function Documentation

unsigned int glimg::CreateTexture | ( | const ImageSet * | pImage,
|  | unsigned int | forceConvertBits
| ) |  |

Creates a texture object from the given ImageSet, with flags.

If an exception is thrown, no OpenGL state will be changed. If a texture was created with glGenTextures before the exception was thrown, it will be deleted with glDeleteTextures after. So this function should be completely exception safe.

Note
  This function requires an active OpenGL context, and it requires that [GLLoad(GL Load) has been initialized.

If an exception is not thrown, then the following OpenGL context state will be changed:

- All `GL_UNPACK_*` state.
- The current texture unit for the texture target of the returned texture (as determined by glimg::GetTextureType) will have texture object 0 bound to it.

If you pass the `USE_DSA` or `FORCE_DSA` flags, and your implementation supports GL_EXT_direct_state_access, then the only state that will be changed are the `GL_UNPACK_*` state.

Parameters

  pImage | The image to upload to OpenGL.
  forceConvertBits | A bitfield containing values from ForcedConvertFlags.

Returns
  The created texture. The texture returned will always be texture-complete, with the proper base and max mipmap level set, and reasonable filtering parameters set on it.

Exceptions

  ImageFormatUnsupportedException | The given ImageFormat cannot be used because the OpenGL implementation doesn't support the functionality necessary to use it.
  TextureUnsupportedException | The type of texture that was asked to be created cannot be created because the OpenGL implementation doesn't support that kind of texture.
  TextureUnexpectedException | The type of texture has not been implemented in GL Image. Appologies for that.
  CannotForceRenderTargetException | Only given if `FORCE_COLOR_RENDERABLE_FMT` is set and a color renderable format cannot be found that is appropriate.
  CannotForceTextureStorage | Only given if `FORCE_TEXTURE_STORAGE` is set and the OpenGL implementation does not implement GL 4.2 or the GL_ARB_texture_storage extension.
  CannotForceDSAUsage | Only given if `FORCE_DSA` is set, and the OpenGL implementation does not implement GL_EXT_direct_state_access.

void glimg::CreateTexture | ( | unsigned int | textureName,
|  | const ImageSet * | pImage,
|  | unsigned int | forceConvertBits
| ) |  |

As CreateTexture(const ImageSet *, unsigned int), but with a texture object provided by the user.

The given texture object must not have been used at all. You cannot even have bound it to the OpenGL context once. It should be fresh from `glGenTextures`.

Exceptions

  ... | Everything that CreateTexture(const ImageSet *, unsigned int) throws.

unsigned int glimg::GetInternalFormat | ( | const ImageFormat & | format,
|  | unsigned int | forceConvertBits
| ) |  |

Retrieves the OpenGL internal format for the given image format and bits.

This function should be used when you want to do the uploading of the texture data yourself. It returns the internal format to use for a particular image format and conversion bits.

Note
  This function requires an active OpenGL context, and it requires that the GL Load has been initialized. It will only return internal formats supported by the current OpenGL context. It will use version numbers, core vs. compatibility, and so forth to detect this.

Format mapping is done as follows. One and two channel glimg::PixelComponents (`RED` and `RG`) will be mapped to luminance and luminance alpha only if the OpenGL context doesn't support `GL_RED` and `GL_RG` textures. Both the EXT extension and the version number will be checked to verify the availability of the feature.

Similarly, if you use `FORCE_LUMINANCE_FMT` on a core context, this function will throw.

Parameters

  format | The image format of the image data to have a texture created for it.
  forceConvertBits | A bitfield containing values from ForcedConvertFlags. These affect how the format is generated.

Returns
  A `GLenum` representing the internal OpenGL format.

Exceptions

  TextureUnsupportedException | The type of texture that was asked to be created cannot be created because the OpenGL implementation doesn't support that kind of texture.
  CannotForceRenderTargetException | Only given if `FORCE_COLOR_RENDERABLE_FMT` is set and a color renderable format cannot be found that is appropriate.

unsigned int glimg::GetTextureType | ( | const ImageSet * | pImage,
|  | unsigned int | forceConvertBits
| ) |  |

Retrieves the texture type for the given ImageSet.

When the glimg::CreateTexture functions are called, they will create a texture with a specific texture type. This is the target that the texture is bound to the context with, and this information is baked into the texture object. It is vital to know what this type will actually be, so that the texture object can be properly bound to the context.

This function will return the texture target that glimg::CreateTexture will create, given exactly the same parameters as glimg::CreateTexture.

Parameters

  pImage | The image that would be uploaded in a glimg::CreateTexture call.
  forceConvertBits | A bitfield containing values from glimg::ForcedConvertFlags.

Returns
  A GLenum for the texture type for a texture that would be created by glimg::CreateTexture.

OpenGLPixelTransferParams glimg::GetUploadFormatType | ( | const ImageFormat & | format,
|  | unsigned int | forceConvertBits
| ) |  |

Retrieves the pixel transfer parameters for the given image format.

    This function should be used if you wish to manually upload image data to OpenGL. It returns the
    pixel transfer parameters for uploading the data.

Note
  This function requires an active OpenGL context, and it requires that GLLoad has been initialized. It will only return pixel transfer parameters supported by the current OpenGL context.

Here is an example of how to use this function:

glimg::ImageSet *pImgSet = ...;
glimg::SingleImage *pImage = pImgSet->GetImage(0);
OpenGLPixelTransferParams params = GetUploadFormatType(pImage->GetFormat(), 0);
glimg::Dimensions dims = pImage->GetDimensions();
glPixelStorei(GL_UNPACK_ALIGNMENT, pImage->GetFormat().LineAlign());
glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0, dims.width, dims.height,
params.format, params.height, pImage->GetImageData());

Parameters

  format | The image format of the image data to have a texture created for it.
  forceConvertBits | A bitfield containing values from glimg::ForcedConvertFlags. These affect how the format is generated.

Returns
  The OpenGL pixel transfer parameters, and a compressed block size field.

Exceptions

  TextureUnsupportedException | The type of texture that was asked to be created cannot be created because the OpenGL implementation doesn't support that kind of texture.
  CannotForceRenderTargetException | Only given if `FORCE_COLOR_RENDERABLE_FMT` is set and a color renderable format cannot be found that is appropriate.