Parameters

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 ”.

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.

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:

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.