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