| 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 4, October 20, 2016 |
| |
| 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 <attrib_list> 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 <target> 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, the |
| format modifier is assumed to be zero. 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 <target> 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 <dpy>. 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 <dpy> is not the handle of a valid EGLDisplay object, the error |
| EGL_BAD_DISPLAY is generated. |
| |
| * If <max_formats> is 0, no formats are returned, but the total number |
| of formats is returned in <num_formats>, and no error is generated. |
| |
| * If <max_formats> has a negative value, the error EGL_BAD_PARAMETER |
| is generated. |
| |
| * If <max_formats> is a positive integer but <formats> 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 <dpy> 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 <external_only>, 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 <dpy> 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 <dpy> is not the handle of a valid EGLDisplay object, the error |
| EGL_BAD_DISPLAY is generated. |
| |
| * If <max_modifiers> is 0, no modifiers are returned, but the total |
| number of modifiers is returned in <num_modifiers>, and no error is |
| generated. |
| |
| * If <max_modifiers> has a negative value, the error EGL_BAD_PARAMETER |
| is generated. |
| |
| * If <max_modifiers> is a positive integer but <modifiers> is NULL, the |
| error EGL_BAD_PARAMETER is generated. |
| |
| * If <format> is not one of the formats advertised by |
| QueryDmaBufFormatsEXT for the same <dpy>, the error EGL_BAD_PARAMETER |
| is generated. |
| |
| |
| Revision History |
| |
| #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. |