man/waffle_context.3.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   Copyright Intel 2012
   7
   8   This manual page is licensed under the Creative Commons Attribution-ShareAlike 3.0 United States License (CC BY-SA 3.0
   9   US). To view a copy of this license, visit http://creativecommons.org.license/by-sa/3.0/us.
  10 -->
  11
  12 <refentry
  13     id="waffle_context"
  14     xmlns:xi="http://www.w3.org/2001/XInclude">
  15
  16   <!-- See http://www.docbook.org/tdg/en/html/refentry.html. -->
  17
  18   <refmeta>
  19     <refentrytitle>waffle_context</refentrytitle>
  20     <manvolnum>3</manvolnum>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>waffle_context</refname>
  25     <refname>waffle_context_create</refname>
  26     <refname>waffle_context_destroy</refname>
  27     <refname>waffle_context_get_native</refname>
  28     <refpurpose>class <classname>waffle_context</classname></refpurpose>
  29   </refnamediv>
  30
  31   <refentryinfo>
  32     <title>Waffle Manual</title>
  33     <productname>waffle</productname>
  34     <xi:include href="common/author-chad.versace.xml"/>
  35     <xi:include href="common/copyright.xml"/>
  36     <xi:include href="common/legalnotice.xml"/>
  37   </refentryinfo>
  38
  39   <refsynopsisdiv>
  40
  41     <funcsynopsis language="C">
  42
  43       <funcsynopsisinfo>
  44 #include &lt;waffle.h&gt;
  45
  46 struct waffle_context;
  47       </funcsynopsisinfo>
  48
  49       <funcprototype>
  50         <funcdef>struct waffle_context* <function>waffle_context_create</function></funcdef>
  51         <paramdef>struct waffle_config *<parameter>config</parameter></paramdef>
  52         <paramdef>struct waffle_context *<parameter>shared_ctx</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  56         <funcdef>bool <function>waffle_context_destroy</function></funcdef>
  57         <paramdef>struct waffle_context *<parameter>self</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>union waffle_native_context* <function>waffle_context_get_native</function></funcdef>
  62         <paramdef>struct waffle_context *<parameter>self</parameter></paramdef>
  63       </funcprototype>
  64
  65     </funcsynopsis>
  66   </refsynopsisdiv>
  67
  68   <refsect1>
  69     <title>Description</title>
  70
  71     <variablelist>
  72
  73       <varlistentry>
  74         <term><type>struct waffle_context</type></term>
  75         <listitem>
  76           <para>
  77             An opaque type.
  78           </para>
  79         </listitem>
  80       </varlistentry>
  81
  82       <varlistentry>
  83         <term><function>waffle_context_create()</function></term>
  84         <listitem>
  85           <para>
  86             Create a context for OpenGL rendering with the properties specified by <parameter>config</parameter>.
  87           </para>
  88
  89           <para>
  90             The returned context's actual properties may differ from,
  91             but are guaranteed to be compatible with,
  92             the properties specified by <parameter>config</parameter>.
  93
  94             See <xref linkend="sect.version_promotion"/> below for details.
  95           </para>
  96
  97           <para>
  98             If <parameter>share_ctx</parameter> is not null, then the newly created context is added to the share group
  99             of <parameter>share_ctx</parameter>. Some data, such as display lists, are shared among all contexts
 100             that belong to the same share group. For details on what data is shared, see the specification for the
 101             relevant native platform:
 102             the <ulink url="http://www.opengl.org/registry/doc/glx1.4.pdf">GLX 1.4 Specification</ulink>,
 103             the <ulink url="http://www.khronos.org/registry/egl/specs/eglspec.1.4.20110406.pdf">EGL 1.4 Specification</ulink>,
 104             or the <ulink url="https://developer.apple.com/library/mac/#documentation/graphicsimaging/reference/CGL_OpenGL/Reference/reference.html">CGL Reference</ulink>.
 105           </para>
 106         </listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term><function>waffle_context_destroy()</function></term>
 111         <listitem>
 112           <para>
 113             Destroy the context and release its memory.
 114           </para>
 115         </listitem>
 116       </varlistentry>
 117
 118       <varlistentry>
 119         <term><function>waffle_context_get_native()</function></term>
 120         <listitem>
 121           <para>
 122             Get the context's underlying native objects. Use
 123             <citerefentry><refentrytitle><function>free</function></refentrytitle><manvolnum>3</manvolnum></citerefentry> to deallocate the
 124             returned pointer.
 125             See <citerefentry><refentrytitle><function>waffle_native</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 126             for the definition of <type>union waffle_native_context</type>.
 127           </para>
 128         </listitem>
 129       </varlistentry>
 130
 131     </variablelist>
 132   </refsect1>
 133
 134   <refsect1
 135       id="sect.version_promotion">
 136
 137     <title>Version Promotion</title>
 138
 139     <para>
 140       The context's requested version and profile is given by the config attributes
 141
 142       <constant>WAFFLE_CONTEXT_MAJOR_VERSION</constant>,
 143       <constant>WAFFLE_CONTEXT_MINOR_VERSION</constant>,
 144       <constant>WAFFLE_CONTEXT_PROFILE</constant>.
 145
 146       The context returned by <function>waffle_context_create</function>
 147       may implement any version and profile
 148       that is backwards compatible with that requested,
 149       as described below.
 150
 151       <itemizedlist>
 152
 153         <listitem>
 154           <para>
 155             If the chosen API is
 156             <constant>WAFFLE_OPENGL_ES1</constant>,
 157             <constant>WAFFLE_OPENGL_ES2</constant>, or
 158             <constant>WAFFLE_OPENGL_ES3</constant>,
 159
 160             then the returned context may implement any of:
 161
 162             <simplelist type="vert">
 163               <member>* The requested version.</member>
 164               <member>* Any later version, so long as no features have been from that later version.</member>
 165             </simplelist>
 166           </para>
 167         </listitem>
 168
 169         <listitem>
 170           <para>
 171             If the chosen API is <constant>WAFFLE_CONTEXT_OPENGL</constant>
 172
 173             and version 3.0 or less is requested,
 174
 175             then the returned context may implement any of:
 176
 177             <simplelist type="vert">
 178               <member>* Any version no less than that requested and no greater than 3.0.</member>
 179               <member>* Version 3.1, if the GL_ARB_compatibility extension is also implemented.</member>
 180               <member>* The compatibility profile of version 3.2 or greater.</member>
 181             </simplelist>
 182           </para>
 183         </listitem>
 184
 185         <listitem>
 186           <para>
 187             If the chosen API is <constant>WAFFLE_CONTEXT_OPENGL</constant>
 188
 189             and version 3.1 is requested,
 190
 191             then the returned context may implement any of:
 192
 193             <simplelist type="vert">
 194               <member>* Version 3.1, with or without the GL_ARB_compatibility extension.</member>
 195               <member>* The core profile of version 3.2 or greater.</member>
 196             </simplelist>
 197           </para>
 198         </listitem>
 199
 200         <listitem>
 201           <para>
 202             If the chosen API is <constant>WAFFLE_CONTEXT_OPENGL</constant>
 203
 204             and version 3.2 or greater is requested,
 205
 206             then the returned context may implement any of:
 207
 208             <simplelist type="vert">
 209               <member>* The requested profile and version.</member>
 210               <member><para>
 211                   * The requested profile of any later version, so long as no features have been from that later
 212                   version and profile.
 213               </para></member>
 214             </simplelist>
 215           </para>
 216         </listitem>
 217
 218       </itemizedlist>
 219     </para>
 220
 221   </refsect1>
 222
 223   <refsect1>
 224     <title>Return Value</title>
 225     <xi:include href="common/return-value.xml"/>
 226   </refsect1>
 227
 228   <refsect1>
 229     <title>Errors</title>
 230
 231     <xi:include href="common/error-codes.xml"/>
 232
 233     <para>
 234       No errors are specific to the <type>waffle_context</type> functions.
 235     </para>
 236   </refsect1>
 237
 238   <xi:include href="common/issues.xml"/>
 239
 240   <refsect1>
 241     <title>See Also</title>
 242     <para>
 243       <citerefentry><refentrytitle>waffle</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 244       <citerefentry><refentrytitle>waffle_config_choose</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 245     </para>
 246   </refsect1>
 247
 248 </refentry>
 249
 250 <!--
 251 vim:tw=120 et ts=2 sw=2:
 252 -->