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