Name EXT_image_dma_buf_import_modifiers Name Strings EGL_EXT_image_dma_buf_import_modifiers Contributors Pekka Paalanen, Collabora Ltd. Louis-Francis Ratté-Boulianne Daniel Stone, Collabora Ltd. Kristian Høgsberg Contacts Pekka Paalanen (pq 'at' collabora 'dot' com) Daniel Stone (daniels 'at' collabora 'dot' com) Status Complete Version Version 5, March 12, 2019 Number EGL Extension #105 Dependencies EGL 1.2 is required. EGL_KHR_image_base is required. EGL_EXT_image_dma_buf_import is required. The EGL implementation must be running on a Linux kernel supporting the dma_buf buffer sharing mechanism. This extension is written against the wording of the EGL 1.2 Specification. In order to support imports for the GL_TEXTURE_EXTERNAL_OES target, a compatible OpenGL ES implementation supporting GL_OES_EGL_image_external must be present. Overview This extension builds on EGL_EXT_image_dma_buf_import, in order to support format modifiers used for tiling, compression, and additional non-linear modes. It also adds support for a fourth auxiliary plane, and queries for the implementation-supported types. New Types None New Procedures and Functions EGLBoolean eglQueryDmaBufFormatsEXT( EGLDisplay dpy, EGLint max_formats, EGLint *formats, EGLint *num_formats) EGLBoolean eglQueryDmaBufModifiersEXT( EGLDisplay dpy, EGLint format, EGLint max_modifiers, EGLuint64KHR *modifiers, EGLBoolean *external_only, EGLint *num_modifiers) New Tokens Accepted as an attribute in the parameter of eglCreateImageKHR: EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT 0x3443 EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT 0x3444 EGL_DMA_BUF_PLANE1_MODIFIER_LO_EXT 0x3445 EGL_DMA_BUF_PLANE1_MODIFIER_HI_EXT 0x3446 EGL_DMA_BUF_PLANE2_MODIFIER_LO_EXT 0x3447 EGL_DMA_BUF_PLANE2_MODIFIER_HI_EXT 0x3448 EGL_DMA_BUF_PLANE3_FD_EXT 0x3440 EGL_DMA_BUF_PLANE3_OFFSET_EXT 0x3441 EGL_DMA_BUF_PLANE3_PITCH_EXT 0x3442 EGL_DMA_BUF_PLANE3_MODIFIER_LO_EXT 0x3449 EGL_DMA_BUF_PLANE3_MODIFIER_HI_EXT 0x344A New Types This extension uses the 64-bit unsigned integer type EGLuint64KHR first introduced by the EGL_KHR_stream extension, but does not depend on that extension. The typedef may be reproduced separately for this extension, if not already present in eglext.h. typedef khronos_uint64_t EGLuint64KHR; Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation) Add to section 2.5.1 "EGLImage Specification" (as defined by the EGL_KHR_image_base specification), in the description of eglCreateImageKHR: If is EGL_LINUX_DMA_BUF_EXT, both or neither of the following attribute values may be given. These attribute values together form an unsigned 64-bit value called a format modifier. Format modifiers are specified by drm_fourcc.h and used as the modifier parameter of the drm_mode_fb_cmd2 ioctl. If neither of the two attributes are given, or if the modifier is explicitly declared to be DRM_FORMAT_MOD_INVALID, the effective format modifier is implementation-defined. The two attributes are: * EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT: The lowest 32 bits of the 64-bit format modifier. * EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT: The highest 32 bits of the 64-bit format modifier. For semi-planar and planar YUV formats, or other formats which require multiple memory planes, planes 1, 2 and 3 are specified by the following attributes, which have the same meanings as defined above for plane 0: * EGL_DMA_BUF_PLANE1_MODIFIER_LO_EXT * EGL_DMA_BUF_PLANE1_MODIFIER_HI_EXT * EGL_DMA_BUF_PLANE2_MODIFIER_LO_EXT * EGL_DMA_BUF_PLANE2_MODIFIER_HI_EXT * EGL_DMA_BUF_PLANE3_FD_EXT * EGL_DMA_BUF_PLANE3_OFFSET_EXT * EGL_DMA_BUF_PLANE3_PITCH_EXT * EGL_DMA_BUF_PLANE3_MODIFIER_LO_EXT * EGL_DMA_BUF_PLANE3_MODIFIER_HI_EXT Modifiers may modify any attribute of a buffer import, including but not limited to adding extra planes to a format which otherwise does not have those planes. As an example, a modifier may add a plane for an external compression buffer to a single-plane format. The exact meaning and effect of any modifier is canonically defined by drm_fourcc.h, not as part of this extension. Implementations are required to validate the full combination of base format and per-plane modifiers, and reject any combination which is not explicitly supported. Add to the list of error conditions for eglCreateImageKHR: * If is EGL_LINUX_DMA_BUF_EXT, and the list of attributes contains EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT but not EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT or vice versa, EGL_BAD_PARAMETER is generated. This applies similarly for planes 1, 2, and 3 also. Add section 2.5.3 "EGLImage dma_buf formats and modifiers" The command EGLBoolean eglQueryDmaBufFormatsEXT( EGLDisplay dpy, EGLint max_formats, EGLint *formats, EGLint *num_formats) is used to query the dma_buf formats supported by . Each format is returned using its FourCC format as defined in the drm_fourcc.h header file. EGL_TRUE is returned if QueryDmaBufFormatsEXT succeeds, EGL_FALSE indicates failure to query. * If is not the handle of a valid EGLDisplay object, the error EGL_BAD_DISPLAY is generated. * If is 0, no formats are returned, but the total number of formats is returned in , and no error is generated. * If has a negative value, the error EGL_BAD_PARAMETER is generated. * If is a positive integer but is NULL, the error EGL_BAD_PARAMETER is generated. The command EGLBoolean eglQueryDmaBufModifiersEXT( EGLDisplay dpy, EGLint format, EGLint max_modifiers, EGLuint64KHR *modifiers, EGLBoolean *external_only, EGLint *num_modifiers) is used to query the dma_buf format modifiers supported by for the given format. The format must be one of those returned by the eglQueryDmaBufFormatsEXT command. The returned modifiers should be defined in the canonical drm_fourcc.h header file. If the user also passes an array for , this will be populated with whether the requested format and modifier combination is only supported for use with the GL_TEXTURE_EXTERNAL_OES texture target. If cannot support any context with GL_OES_EGL_image_external, the array will be populated with EGL_FALSE. EGL_TRUE is returned if QueryDmaBufModifiersEXT succeeds, EGL_FALSE indicates failure. * If is not the handle of a valid EGLDisplay object, the error EGL_BAD_DISPLAY is generated. * If is 0, no modifiers are returned, but the total number of modifiers is returned in , and no error is generated. * If has a negative value, the error EGL_BAD_PARAMETER is generated. * If is a positive integer but is NULL, the error EGL_BAD_PARAMETER is generated. * If is not one of the formats advertised by QueryDmaBufFormatsEXT for the same , the error EGL_BAD_PARAMETER is generated. Revision History #5 (Daniel Stone, March 12, 2019) - Correct description of behaviour when a modifier is not explicitly given; zero is not correct as it is an explicit modifier itself (linear). #4 (Daniel Stone, October 20, 2016) - Switch to EGLuint64KHR for modifier types. #3 (Daniel Stone, October 20, 2016) - Clarify that the effect that modifiers can have. - Disambiguate references to displays. - Explicitly refer to max_formats/max_modifiers behaviour when zero. #2 (Daniel Stone, September 29, 2016) - Add missing tokens for plane 3 FD/offset/pitch. - Fix description. - Allow max_formats/max_modifiers to be zero, to get the counter. - Add external_only to modifiers query. #1 (Pekka Paalanen, October 14, 2015) - Initial draft.