eglCreateImage - EGL Reference Pages

## Name

eglCreateImage — Create a new EGLImage object

## C Specification

`EGLImage eglCreateImage(` | (EGLDisplay display,
| EGLContext context,
| EGLenum target,
| EGLClientBuffer buffer,
| const EGLAttrib *attrib_list`)`;

## Parameters

`display`

  Specifies the EGL display connection.

`context`

  Specifies the client API context for which the image is created.

`target`

  Specifies the type of resource used as the image source.

`buffer`

  Specifies the resource to be used as the image source.

`attrib_list`

  Specifies attributes used to select sub-sections of the resource to be used as the image source.

## Description

`eglCreateImage` is used to create an EGLImage object from an existing image resource `buffer`. `display` specifies the EGL display used for this operation. `context` specifies the EGL client API context used for this operation, or `EGL_NO_CONTEXT` if a client API context is not required. `target` specifies the type of resource being used as the EGLImage source (examples include two-dimensional textures in OpenGL ES contexts and VGImage objects in OpenVG contexts). `buffer` is the name (or handle) of a resource to be used as the EGLImage source, cast into the type EGLClientBuffer. `attrib_list` is a list of attribute-value pairs which is used to select sub-sections of `buffer` for use as the EGLImage source, such as mipmap levels for OpenGL ES texture map resources, as well as behavioral options, such as whether to preserve pixel data during creation. If `attrib_list` is non-`NULL`, the last attribute specified in the list must be `EGL_NONE`.

The resource specified by `display`, `context`, `target`, `buffer`, and `attrib_list` must not itself be an EGLImage sibling, or bound to a pbuffer EGLSurface resource (`eglBindTexImage`, `eglCreatePbufferFromClientBuffer`).

Values accepted for `target` are shown in table Table 1, “ Legal values for `eglCreateImage` `target` ”.

Table 1. Legal values for `eglCreateImage` `target`

`target` | Notes
--- | ---
`EGL_GL_TEXTURE_2D` | Used for GL 2D texture images
`EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X` | Used for the +X face of GL cubemap texture images
`EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X` | Used for the -X face of GL cubemap texture images
`EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y` | Used for the +Y face of GL cubemap texture images
`EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y` | Used for the -Y face of GL cubemap texture images
`EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z` | Used for the +Z face of GL cubemap texture images
`EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z` | Used for the -Z face of GL cubemap texture images
`EGL_GL_TEXTURE_3D` | Used for OpenGL and OpenGL ES 3D texture images
`EGL_GL_RENDERBUFFER` | Used for OpenGL and OpenGL ES renderbuffer images

Attribute names accepted in `attrib_list` are shown in table Table 2, “ Legal attributes for `eglCreateImage` `attrib_list` parameter ”, together with the `target` for which each attribute name is valid, and the default value used for each attribute if it is not included in `attrib_list`.

Table 2. Legal attributes for `eglCreateImage` `attrib_list` parameter

`target` | Notes |  |
Attribute | Description | Valid `target`s | Default Value
`EGL_NONE` | Marks the end of the attribute-value list | All | N/A
`EGL_GL_TEXTURE_LEVEL` | Specifies the mipmap level used as the EGLImage source. Must be part of the complete texture object `buffer` | `EGL_GL_TEXTURE_2D`, `EGL_GL_TEXTURE_CUBE_MAP_*`, or `EGL_GL_TEXTURE_3D` | 0
`EGL_GL_TEXTURE_ZOFFSET` | Specifies the depth offset of the image to use as the EGLImage source. Must be part of the complete texture object `buffer` | `EGL_GL_TEXTURE_3D` | 0
`EGL_IMAGE_PRESERVED` | Whether to preserve pixel data | All | `EGL_FALSE`

`eglCreateImage` returns an EGLImage object corresponding to the image data specified by `display`, `context`, `target`, `buffer` and `attrib_list` which may be referenced by client API operations.

If `target` is `EGL_GL_TEXTURE_2D`, `EGL_GL_TEXTURE_3D`, `EGL_GL_RENDERBUFFER`, `EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X`, `EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X`, `EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y`, `EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y`, `EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z`, or `EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z`, `display` must be a valid EGLDisplay, and `context` must be a valid OpenGL or OpenGL ES API context on that display.

If `target` is `EGL_GL_TEXTURE_2D`, `buffer` must be the name of a nonzero, `GL_TEXTURE_2D` target texture object, cast into the type EGLClientBuffer.

If `target` is one of the `EGL_GL_TEXTURE_CUBE_MAP_*` enumerants, `buffer` must be the name of a nonzero, `GL_TEXTURE_CUBE_MAP` (or equivalent in GL extensions) target texture object, cast into the type EGLClientBuffer.

If `target` is `EGL_GL_TEXTURE_3D`, `buffer` must be the name of a nonzero, `GL_TEXTURE_3D` (or equivalent in GL extensions) target texture object, cast into the type EGLClientBuffer.

`attrib_list` should specify the mipmap level (`EGL_GL_TEXTURE_LEVEL`) and, where applicable, z-offset (`EGL_GL_TEXTURE_ZOFFSET`) which will be used as the EGLImage source; If not specified, the default values listed in table Table 2, “ Legal attributes for `eglCreateImage` `attrib_list` parameter ” will be used instead. Additional values specified in are ignored.

There must exist some levels x and y such that the mipmap level requested lies between x and y (inclusive), the texture would be mipmap complete were x substituted for the base level and y substituted for the max level, and all levels less than x or greater than y are unspecified. For cubemaps a single pair x and y must apply to all faces. For three-dimensional textures, the specified z-offset must be smaller than the depth of the specified mipmap level.

If `target` is `EGL_GL_RENDERBUFFER`, `buffer` must be the name of a complete, nonzero, non-multisampled `GL_RENDERBUFFER` (or equivalent in extensions) target object, cast into the type EGLClientBuffer. Values specified in `attrib_list` are ignored.

If the value of attribute `EGL_IMAGE_PRESERVED` is `EGL_FALSE` (the default), then all pixel data values associated with `buffer` will be undefined after `eglCreateImage` returns.

If the value of attribute `EGL_IMAGE_PRESERVED` is `EGL_TRUE`, then all pixel data values associated with `buffer` are preserved.

## Errors

`eglCreateImage` returns `EGL_NO_IMAGE` on failure. The contents of `buffer` will be unaffected.

If `display` is not the handle of a valid EGLDisplay object, the error `EGL_BAD_DISPLAY` is generated.

If `context` is neither the handle of a valid EGLContext object on `display` nor `EGL_NO_CONTEXT`, the error `EGL_BAD_CONTEXT` is generated.

If `target` is not one of the values in table Table 1, “ Legal values for `eglCreateImage` `target` ”, the error `EGL_BAD_PARAMETER` is generated.

If `target` is `EGL_GL_TEXTURE_2D`, `EGL_GL_TEXTURE_CUBE_MAP_*`, `EGL_GL_RENDERBUFFER` or `EGL_GL_TEXTURE_3D`, and `display` is not a valid EGLDisplay, the error `EGL_BAD_DISPLAY` is generated.

If `target` is `EGL_GL_TEXTURE_2D`, `EGL_GL_TEXTURE_CUBE_MAP_*`, `EGL_GL_RENDERBUFFER` or `EGL_GL_TEXTURE_3D`, and `context` is not a valid EGLContext, the error `EGL_BAD_CONTEXT` is generated.

If `target` is `EGL_GL_TEXTURE_2D`, `EGL_GL_TEXTURE_CUBE_MAP_*`, `EGL_GL_RENDERBUFFER` or `EGL_GL_TEXTURE_3D`, and `context` is not a valid GL context, or does not match the `display`, the error `EGL_BAD_MATCH` is generated.

If `target` is `EGL_GL_TEXTURE_2D`, `EGL_GL_TEXTURE_CUBE_MAP_*` or `EGL_GL_TEXTURE_3D` and `buffer` is not the name of a texture object of type `target`, the error `EGL_BAD_PARAMETER` is generated.

If `target` is `EGL_GL_RENDERBUFFER` and `buffer` is not the name of a renderbuffer object, or if `buffer` is the name of a multisampled renderbuffer object, the error `EGL_BAD_PARAMETER` is generated.

If `EGL_GL_TEXTURE_LEVEL` is nonzero, `target` is `EGL_GL_TEXTURE_2D`, `EGL_GL_TEXTURE_CUBE_MAP_*` or `EGL_GL_TEXTURE_3D`, and `buffer` is not the name of a complete GL texture object, the error `EGL_BAD_PARAMETER` is generated.

If `EGL_GL_TEXTURE_LEVEL` is 0, `target` is `EGL_GL_TEXTURE_2D`, `EGL_GL_TEXTURE_CUBE_MAP_*` or `EGL_GL_TEXTURE_3D`, `buffer` is the name of an incomplete GL texture object, and any mipmap levels other than mipmap level 0 are specified, the error `EGL_BAD_PARAMETER` is generated.

If `EGL_GL_TEXTURE_LEVEL` is 0, `target` is `EGL_GL_TEXTURE_2D` or `EGL_GL_TEXTURE_3D`, `buffer` is not the name of a complete GL texture object, and mipmap level 0 is not specified, the error `EGL_BAD_PARAMETER` is generated.

If `EGL_GL_TEXTURE_LEVEL` is 0, `target` is `EGL_GL_TEXTURE_CUBE_MAP_*`, `buffer` is not the name of a complete GL texture object, and one or more faces do not have mipmap level 0 specified, the error `EGL_BAD_PARAMETER` is generated.

If `target` is `EGL_GL_TEXTURE_2D`, `EGL_GL_TEXTURE_CUBE_MAP_*`, `EGL_GL_RENDERBUFFER` or `EGL_GL_TEXTURE_3D` and `buffer` refers to the default GL texture object (0) for the corresponding GL target, the error `EGL_BAD_PARAMETER` is generated.

If `target` is `EGL_GL_TEXTURE_2D`, `EGL_GL_TEXTURE_CUBE_MAP_*`, or `EGL_GL_TEXTURE_3D`, and the value specified in `attrib_list` for `EGL_GL_TEXTURE_LEVEL` is not a valid mipmap level for the specified GL texture object `buffer`, the error `EGL_BAD_MATCH` is generated.

If `target` is `EGL_GL_TEXTURE_3D`, and the value specified in `attrib_list` for `EGL_GL_TEXTURE_ZOFFSET` exceeds the depth of the specified mipmap level-of-detail in `buffer`, the error `EGL_BAD_PARAMETER` is generated.

If an attribute specified in `attrib_list` is not one of the attributes shown in table Table 2, “ Legal attributes for `eglCreateImage` `attrib_list` parameter ”, the error `EGL_BAD_PARAMETER` is generated.

If an attribute specified in `attrib_list` is not a valid attribute for `target`, as shown in table Table 2, “ Legal attributes for `eglCreateImage` `attrib_list` parameter ”, the error `EGL_BAD_MATCH` is generated.

If the resource specified by `display`, `context`, `target`, `buffer` and `attrib_list` has an off-screen buffer bound to it (e.g., by a previous call to `eglBindTexImage`), the error `EGL_BAD_ACCESS` is generated.

If the resource specified by `display`, `context`, `target`, `buffer` and `attrib_list` is bound to an off-screen buffer (e.g., by a previous call to `eglCreatePbufferFromClientBuffer`), the error `EGL_BAD_ACCESS` is generated.

If the resource specified by `display`, `context`, `target`, `buffer` and `attrib_list` is itself an EGLImage sibling, the error `EGL_BAD_ACCESS` is generated.

If insufficient memory is available to complete the specified operation, the error `EGL_BAD_ALLOC` is generated.

If the value specified in `attrib_list` for `EGL_IMAGE_PRESERVED` is `EGL_TRUE`, and an EGLImage handle cannot be created from the specified resource such that the pixel data values in `buffer` are preserved, the error `EGL_BAD_ACCESS` is generated.

Note that the success or failure of `eglCreateImage` should not affect the ability to use `buffer` in its original API context (or context share group) (although the pixel data values will be undefined if the command succeeds and the value of `EGL_IMAGE_PRESERVED` is not `EGL_TRUE`).

## Lifetime and Usage of EGLImages

Once an EGLImage is created from an EGLImage source, the memory associated with the EGLImage source will remain allocated (and all EGLImage siblings in all client API contexts will be useable) as long as either of the following conditions is true:

- Any EGLImage siblings exist in any client API context

- The EGLImage object exists inside EGL

The semantics for specifying, deleting and using EGLImage siblings are client API-specific, and are described in the appropriate API specifications.

If an application specifies an EGLImage sibling as the destination for rendering and/or pixel download operations (e.g., as an OpenGL or OpenGL ES framebuffer object, `glTexSubImage2D`, etc.), the modified image results will be observed by all EGLImage siblings in all client API contexts. If multiple client API contexts access EGLImage sibling resources simultaneously, with one or more context modifying the image data, rendering results in all contexts accessing EGLImage siblings are undefined.

Respecification and/or deletion of any EGLImage sibling (i.e., both EGLImage source and EGLImage target resources) inside a client API context (by issuing a subsequent call to commands such as `glTexImage*` or `glDeleteTextures`, with the EGLImage sibling resource as the target of the operation) affects only that client API context and other contexts within its share group. For an OpenGL or OpenGL ES context, respecification always results in orphaning of the EGLImage, and may also include allocation of additional memory for the respecified resource and/or copying of the EGLImage pixel data.

Note: Behavior of other types of client APIs generally follows the OpenGL and OpenGL ES behavior described here, although this is not mandated yet.

Operations inside EGL or any client API context which may affect the lifetime of an EGLImage (or the memory allocated for the EGLImage), such as respecifying and/or deleting an EGLImage sibling inside a client API context, must be atomic.

Applications may create client API resources from an EGLImage using client API extensions outside the scope of this document (such as `GL_OES_EGL_image`, which creates OpenGL ES texture and renderbuffer objects). If the EGLImage used to create the client resource was created with the `EGL_IMAGE_PRESERVED` attribute set to `EGL_TRUE`, then the pixel data values associated with the image will be preserved after creating the client resource; otherwise, the pixel data values will be undefined. If the EGLImage was created with the `EGL_IMAGE_PRESERVED` attribute set to `EGL_TRUE`, and EGL is unable to create the client resource without modifying the pixel values, then creation will fail and the pixel data values will be preserved.

## Notes

`eglCreateImage` is available only if the EGL version is 1.5 or greater.

## See Also

eglBindTexImage, eglCreatePbufferFromClientBuffer, eglDestroyImage, `glDeleteTextures`, `glTexImage*`, `glTexSubImage2D`

Copyright © 2003-2014 The Khronos Group Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.