1<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglQuerySurface"> 2 <info> 3 <copyright> 4 <year>2003-2018</year> 5 <holder>The Khronos Group Inc.</holder> 6 </copyright> 7 </info> 8 <refmeta> 9 <refentrytitle>eglQuerySurface</refentrytitle> 10 <manvolnum>3G</manvolnum> 11 </refmeta> 12 <refnamediv> 13 <refname>eglQuerySurface</refname> 14 <refpurpose> 15 return <acronym>EGL</acronym> surface information 16 </refpurpose> 17 </refnamediv> 18 <refsynopsisdiv> 19 <title>C Specification</title> 20 <funcsynopsis> 21 <funcprototype> 22 <funcdef>EGLBoolean <function>eglQuerySurface</function></funcdef> 23 <paramdef>EGLDisplay <parameter>display</parameter></paramdef> 24 <paramdef>EGLSurface <parameter>surface</parameter></paramdef> 25 <paramdef>EGLint <parameter>attribute</parameter></paramdef> 26 <paramdef>EGLint * <parameter>value</parameter></paramdef> 27 </funcprototype> 28 </funcsynopsis> 29 </refsynopsisdiv> 30 <refsect1 xml:id="parameters"><title>Parameters</title> 31 <variablelist> 32 <varlistentry> 33 <term><parameter>display</parameter></term> 34 <listitem> 35 <para> 36 Specifies the EGL display connection. 37 </para> 38 </listitem> 39 </varlistentry> 40 <varlistentry> 41 <term><parameter>surface</parameter></term> 42 <listitem> 43 <para> 44 Specifies the EGL surface to query. 45 </para> 46 </listitem> 47 </varlistentry> 48 <varlistentry> 49 <term><parameter>attribute</parameter></term> 50 <listitem> 51 <para> 52 Specifies the EGL surface attribute to be returned. 53 </para> 54 </listitem> 55 </varlistentry> 56 <varlistentry> 57 <term><parameter>value</parameter></term> 58 <listitem> 59 <para> 60 Returns the requested value. 61 </para> 62 </listitem> 63 </varlistentry> 64 </variablelist> 65 </refsect1> 66 <refsect1 xml:id="description"><title>Description</title> 67 <para> 68 <function>eglQuerySurface</function> returns in 69 <parameter>value</parameter> the value of 70 <parameter>attribute</parameter> for <parameter>surface</parameter>. 71 <parameter>attribute</parameter> can be one of the following: 72 </para> 73 <variablelist> 74 <varlistentry> 75 <term><constant>EGL_CONFIG_ID</constant></term> 76 <listitem><para> 77 Returns the ID of the EGL frame buffer configuration 78 with respect to which the surface was created. 79 </para></listitem> 80 </varlistentry> 81 <varlistentry> 82 <term><constant>EGL_GL_COLORSPACE</constant></term> 83 <listitem><para> 84 Returns the color space used by OpenGL and OpenGL ES 85 when rendering to the surface, either 86 <constant>EGL_GL_COLORSPACE_SRGB</constant> or 87 <constant>EGL_GL_COLORSPACE_LINEAR</constant>. 88 </para></listitem> 89 </varlistentry> 90 <varlistentry> 91 <term><constant>EGL_HEIGHT</constant></term> 92 <listitem><para> 93 Returns the height of the surface in pixels. 94 </para></listitem> 95 </varlistentry> 96 <varlistentry> 97 <term><constant>EGL_HORIZONTAL_RESOLUTION</constant></term> 98 <listitem><para> 99 Returns the horizontal dot pitch of the display on 100 which a window surface is visible. The value 101 returned is equal to the actual dot pitch, in 102 pixels/meter, multiplied by the constant value 103 <constant>EGL_DISPLAY_SCALING</constant>. 104 </para></listitem> 105 </varlistentry> 106 <varlistentry> 107 <term><constant>EGL_LARGEST_PBUFFER</constant></term> 108 <listitem><para> 109 Returns the same attribute value specified when the 110 surface was created with 111 <citerefentry><refentrytitle>eglCreatePbufferSurface</refentrytitle></citerefentry>. 112 For a window or pixmap surface, 113 <parameter>value</parameter> is not modified. 114 </para></listitem> 115 </varlistentry> 116 <varlistentry> 117 <term><constant>EGL_MIPMAP_LEVEL</constant></term> 118 <listitem><para> 119 Returns which level of the mipmap to render to, if 120 texture has mipmaps. 121 </para></listitem> 122 </varlistentry> 123 <varlistentry> 124 <term><constant>EGL_MIPMAP_TEXTURE</constant></term> 125 <listitem><para> 126 Returns <constant>EGL_TRUE</constant> if texture has 127 mipmaps, <constant>EGL_FALSE</constant> otherwise. 128 </para></listitem> 129 </varlistentry> 130 <varlistentry> 131 <term><constant>EGL_MULTISAMPLE_RESOLVE</constant></term> 132 <listitem> 133 <para> 134 Returns the filter used when resolving the 135 multisample buffer. The filter may be either 136 <constant>EGL_MULTISAMPLE_RESOLVE_DEFAULT</constant> 137 or <constant>EGL_MULTISAMPLE_RESOLVE_BOX</constant>, 138 as described for 139 <citerefentry><refentrytitle>eglSurfaceAttrib</refentrytitle></citerefentry>. 140 </para> 141 </listitem> 142 </varlistentry> 143 <varlistentry> 144 <term><constant>EGL_PIXEL_ASPECT_RATIO</constant></term> 145 <listitem><para> 146 Returns the aspect ratio of an individual pixel (the 147 ratio of a pixel's width to its height). The value 148 returned is equal to the actual aspect ratio 149 multiplied by the constant value 150 <constant>EGL_DISPLAY_SCALING</constant>. 151 </para></listitem> 152 </varlistentry> 153 <varlistentry> 154 <term><constant>EGL_RENDER_BUFFER</constant></term> 155 <listitem><para> 156 Returns the buffer which client API rendering is 157 requested to use. For a window surface, this is the 158 same attribute value specified when the surface was 159 created. For a pbuffer surface, it is always 160 <constant>EGL_BACK_BUFFER</constant>. For a pixmap 161 surface, it is always 162 <constant>EGL_SINGLE_BUFFER</constant>. To determine 163 the actual buffer being rendered to by a context, 164 call 165 <citerefentry><refentrytitle>eglQueryContext</refentrytitle></citerefentry>. 166 </para></listitem> 167 </varlistentry> 168 <varlistentry> 169 <term><constant>EGL_SWAP_BEHAVIOR</constant></term> 170 <listitem><para> 171 Returns the effect on the color buffer when posting 172 a surface with 173 <citerefentry><refentrytitle>eglSwapBuffers</refentrytitle></citerefentry>. 174 Swap behavior may be either 175 <constant>EGL_BUFFER_PRESERVED</constant> or 176 <constant>EGL_BUFFER_DESTROYED</constant>, as 177 described for 178 <citerefentry><refentrytitle>eglSurfaceAttrib</refentrytitle></citerefentry>. 179 </para></listitem> 180 </varlistentry> 181 <varlistentry> 182 <term><constant>EGL_TEXTURE_FORMAT</constant></term> 183 <listitem><para> 184 Returns format of texture. Possible values are 185 <constant>EGL_NO_TEXTURE</constant>, 186 <constant>EGL_TEXTURE_RGB</constant>, and 187 <constant>EGL_TEXTURE_RGBA</constant>. 188 </para></listitem> 189 </varlistentry> 190 <varlistentry> 191 <term><constant>EGL_TEXTURE_TARGET</constant></term> 192 <listitem><para> 193 Returns type of texture. Possible values are 194 <constant>EGL_NO_TEXTURE</constant>, or 195 <constant>EGL_TEXTURE_2D</constant>. 196 </para></listitem> 197 </varlistentry> 198 <varlistentry> 199 <term><constant>EGL_VERTICAL_RESOLUTION</constant></term> 200 <listitem><para> 201 Returns the vertical dot pitch of the display on 202 which a window surface is visible. The value 203 returned is equal to the actual dot pitch, in 204 pixels/meter, multiplied by the constant value 205 <constant>EGL_DISPLAY_SCALING</constant>. 206 </para></listitem> 207 </varlistentry> 208 <varlistentry> 209 <term><constant>EGL_VG_ALPHA_FORMAT</constant></term> 210 <listitem><para> 211 Returns the interpretation of alpha values used by 212 OpenVG when rendering to the surface, either 213 <constant>EGL_VG_ALPHA_FORMAT_NONPRE</constant> or 214 <constant>EGL_VG_ALPHA_FORMAT_PRE</constant>. 215 </para></listitem> 216 </varlistentry> 217 <varlistentry> 218 <term><constant>EGL_VG_COLORSPACE</constant></term> 219 <listitem><para> 220 Returns the color space used by OpenVG when rendering to 221 the surface, either 222 <constant>EGL_VG_COLORSPACE_sRGB</constant> or 223 <constant>EGL_VG_COLORSPACE_LINEAR</constant>. 224 </para></listitem> 225 </varlistentry> 226 <varlistentry> 227 <term><constant>EGL_WIDTH</constant></term> 228 <listitem><para> 229 Returns the width of the surface in pixels. 230 </para></listitem> 231 </varlistentry> 232 </variablelist> 233 </refsect1> 234 <refsect1 xml:id="notes"><title>Notes</title> 235 <para> 236 Attribute <constant>EGL_GL_COLORSPACE</constant> is supported 237 only if the EGL version is 1.5 or greater. 238 </para> 239 <para> 240 Attribute <constant>EGL_MULTISAMPLE_RESOLVE</constant> is 241 supported only if the EGL version is 1.4 or greater. 242 </para> 243 <para> 244 Attributes <constant>EGL_DISPLAY_SCALING</constant>. 245 <constant>EGL_HORIZONTAL_RESOLUTION</constant>, 246 <constant>EGL_PIXEL_ASPECT_RATIO</constant>, 247 <constant>EGL_RENDER_BUFFER</constant>, 248 <constant>EGL_SWAP_BEHAVIOR</constant>, and 249 <constant>EGL_VERTICAL_RESOLUTION</constant> are supported 250 only if the EGL version is 1.2 or greater. 251 </para> 252 <para> 253 Querying attributes <constant>EGL_TEXTURE_FORMAT</constant>, 254 <constant>EGL_TEXTURE_TARGET</constant>, 255 <constant>EGL_MIPMAP_TEXTURE</constant>, or 256 <constant>EGL_MIPMAP_LEVEL</constant> for a non-pbuffer 257 surface is not an error, but <parameter>value</parameter> is 258 not modified. 259 </para> 260 <para> 261 <constant>EGL_DISPLAY_SCALING</constant> is the constant 262 value 10000. Floating-point values such as resolution and 263 pixel aspect ratio are scaled by this value before being 264 returned as integers so that sufficient precision to be 265 meaningful will be retained in the returned value. 266 </para> 267 <para> 268 For an offscreen (pbuffer or pixmap) surface, or a surface 269 whose pixel dot pitch or aspect ratio are unknown, querying 270 <constant>EGL_HORIZONTAL_RESOLUTION</constant>, 271 <constant>EGL_PIXEL_ASPECT_RATIO</constant>, or 272 <constant>EGL_VERTICAL_RESOLUTION</constant> will return the 273 constant value <constant>EGL_UNKNOWN</constant> (-1). 274 </para> 275 </refsect1> 276 <refsect1 xml:id="errors"><title>Errors</title> 277 <para> 278 <constant>EGL_FALSE</constant> is returned on failure, 279 <constant>EGL_TRUE</constant> otherwise. 280 <parameter>value</parameter> is not modified when 281 <constant>EGL_FALSE</constant> is returned. 282 </para> 283 <para> 284 <constant>EGL_BAD_DISPLAY</constant> is generated if 285 <parameter>display</parameter> is not an EGL display connection. 286 </para> 287 <para> 288 <constant>EGL_NOT_INITIALIZED</constant> is generated if 289 <parameter>display</parameter> has not been initialized. 290 </para> 291 <para> 292 <constant>EGL_BAD_SURFACE</constant> is generated if 293 <parameter>surface</parameter> is not an EGL surface. 294 </para> 295 <para> 296 <constant>EGL_BAD_ATTRIBUTE</constant> is generated if 297 <parameter>attribute</parameter> is not a valid surface attribute. 298 </para> 299 </refsect1> 300 <refsect1 xml:id="seealso"><title>See Also</title> 301 <para> 302 <citerefentry><refentrytitle>eglCreatePbufferSurface</refentrytitle></citerefentry>, 303 <citerefentry><refentrytitle>eglCreatePixmapSurface</refentrytitle></citerefentry>, 304 <citerefentry><refentrytitle>eglCreateWindowSurface</refentrytitle></citerefentry>, 305 <citerefentry><refentrytitle>eglSurfaceAttrib</refentrytitle></citerefentry>, 306 <citerefentry><refentrytitle>eglSwapBuffers</refentrytitle></citerefentry> 307 </para> 308 </refsect1> 309 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/> 310</refentry> 311