blob: 9308a0dc239030175736cf44876bde1df4ca137a [file] [log] [blame]
{{+bindTo:partials.standard_nacl_api}}
<h1>pp::Graphics3D Class Reference</h1>
<div id="doxygen-ref">
{{- dummy div to appease doxygen -}}
<div>
<!-- Generated by Doxygen 1.7.6.1 -->
</div>
<!--header-->
<div class="contents">
<!-- doxytag: class="pp::Graphics3D" --><!-- doxytag: inherits="pp::Resource" --><div class="dynheader">
Inheritance diagram for pp::Graphics3D:</div>
<div class="dyncontent">
<div class="center"><img src="classpp_1_1_graphics3_d__inherit__graph.png" border="0" usemap="#pp_1_1_graphics3_d_inherit__map" alt="Inheritance graph" /></div>
<map name="pp_1_1_graphics3_d_inherit__map" id="pp_1_1_graphics3_d_inherit__map">
<area shape="rect" id="node2" href="classpp_1_1_resource.html" title="A reference counted module resource." alt="" coords="13,5,117,32"></area></map>
<center><span class="legend">[<a href="graph_legend.html">legend</a>]</span></center></div>
<p><a href="classpp_1_1_graphics3_d-members.html">List of all members.</a></p>
<h2>
Public Member Functions</h2><table class="memberdecls">
<tr><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_graphics3_d.html#a36b6d8c818d0af11128d9522dd7f8bc2">Graphics3D</a> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_graphics3_d.html#a072a5e20977e193d02b2e509ad72d11e">Graphics3D</a> (const <a class="el" href="classpp_1_1_instance_handle.html">InstanceHandle</a> &amp;instance, const int32_t attrib_list[])</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_graphics3_d.html#a53586ebd53025ff6e1e0c4b89e471f68">Graphics3D</a> (const <a class="el" href="classpp_1_1_instance_handle.html">InstanceHandle</a> &amp;instance, const <a class="el" href="classpp_1_1_graphics3_d.html">Graphics3D</a> &amp;share_context, const int32_t attrib_list[])</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_graphics3_d.html#a134128672575294aeb17c263189b9da0">~Graphics3D</a> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_graphics3_d.html#ae4527f4526a090c05ab7d9ce9fafb3de">GetAttribs</a> (int32_t attrib_list[]) const </td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_graphics3_d.html#a504e04ec5f21e324439fe8edc3622957">SetAttribs</a> (const int32_t attrib_list[])</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_graphics3_d.html#a21b887529bdba99089ff3c1fa16d3d7c">ResizeBuffers</a> (int32_t width, int32_t height)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_graphics3_d.html#ae1d1c071bf2737ab310a32558ec5f507">SwapBuffers</a> (const <a class="el" href="classpp_1_1_completion_callback.html">CompletionCallback</a> &amp;cc)</td></tr>
</table>
<hr /><a name="details" id="details"></a><h2>Detailed Description</h2>
<div class="textblock"><p>This class represents a 3D rendering context in the browser. </p>
</div><hr /><h2>Constructor &amp; Destructor Documentation</h2>
<a class="anchor" id="a36b6d8c818d0af11128d9522dd7f8bc2"></a><!-- doxytag: member="pp::Graphics3D::Graphics3D" ref="a36b6d8c818d0af11128d9522dd7f8bc2" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classpp_1_1_graphics3_d.html#a36b6d8c818d0af11128d9522dd7f8bc2">pp::Graphics3D::Graphics3D</a> </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Default constructor for creating an <a class="el" href="classpp_1_1_resource.html#a859068e34cdc2dc0b78754c255323aa9" title="This functions determines if this resource is invalid or uninitialized.">is_null()</a> <a class="el" href="classpp_1_1_graphics3_d.html" title="This class represents a 3D rendering context in the browser.">Graphics3D</a> object. </p>
</div>
</div>
<a class="anchor" id="a072a5e20977e193d02b2e509ad72d11e"></a><!-- doxytag: member="pp::Graphics3D::Graphics3D" ref="a072a5e20977e193d02b2e509ad72d11e" args="(const InstanceHandle &amp;instance, const int32_t attrib_list[])" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classpp_1_1_graphics3_d.html#a36b6d8c818d0af11128d9522dd7f8bc2">pp::Graphics3D::Graphics3D</a> </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classpp_1_1_instance_handle.html">InstanceHandle</a> &amp;&#160;</td>
<td class="paramname"><em>instance</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t&#160;</td>
<td class="paramname"><em>attrib_list</em>[]&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>A constructor for creating and initializing a 3D rendering context. </p>
<p>The returned context is created off-screen and must be attached to a module instance using <code><a class="el" href="classpp_1_1_instance.html#a147a1c1817a7a1fb2b76f5c87ab08899" title="BindGraphics() binds the given graphics as the current display surface.">Instance::BindGraphics</a></code> to draw on the web page.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">instance</td><td>The instance with which this resource will be associated.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">attrib_list</td><td>The list of attributes (name=value pairs) for the context. The list is terminated with <code>PP_GRAPHICS3DATTRIB_NONE</code>. The <code>attrib_list</code> may be <code>NULL</code> or empty (first attribute is <code>PP_GRAPHICS3DATTRIB_NONE</code>). If an attribute is not specified in <code>attrib_list</code>, then the default value is used.</td></tr>
</table>
</dd>
</dl>
<p>Attributes are classified into two categories:</p>
<p>1. AtLeast: The attribute value in the returned context will meet or exceed the value requested when creating the object. 2. Exact: The attribute value in the returned context is equal to the value requested when creating the object.</p>
<p>AtLeast attributes are (all have default values of 0):</p>
<p><code>PP_GRAPHICS3DATTRIB_ALPHA_SIZE</code> <code>PP_GRAPHICS3DATTRIB_BLUE_SIZE</code> <code>PP_GRAPHICS3DATTRIB_GREEN_SIZE</code> <code>PP_GRAPHICS3DATTRIB_RED_SIZE</code> <code>PP_GRAPHICS3DATTRIB_DEPTH_SIZE</code> <code>PP_GRAPHICS3DATTRIB_STENCIL_SIZE</code> <code>PP_GRAPHICS3DATTRIB_SAMPLES</code> <code>PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS</code></p>
<p>Exact attributes are:</p>
<p><code>PP_GRAPHICS3DATTRIB_WIDTH</code> Default 0 <code>PP_GRAPHICS3DATTRIB_HEIGHT</code> Default 0 <code>PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR</code> Default: Implementation defined.</p>
<p>On failure, the object will be <a class="el" href="classpp_1_1_resource.html#a859068e34cdc2dc0b78754c255323aa9" title="This functions determines if this resource is invalid or uninitialized.">is_null()</a>. </p>
</div>
</div>
<a class="anchor" id="a53586ebd53025ff6e1e0c4b89e471f68"></a><!-- doxytag: member="pp::Graphics3D::Graphics3D" ref="a53586ebd53025ff6e1e0c4b89e471f68" args="(const InstanceHandle &amp;instance, const Graphics3D &amp;share_context, const int32_t attrib_list[])" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classpp_1_1_graphics3_d.html#a36b6d8c818d0af11128d9522dd7f8bc2">pp::Graphics3D::Graphics3D</a> </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classpp_1_1_instance_handle.html">InstanceHandle</a> &amp;&#160;</td>
<td class="paramname"><em>instance</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const <a class="el" href="classpp_1_1_graphics3_d.html">Graphics3D</a> &amp;&#160;</td>
<td class="paramname"><em>share_context</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const int32_t&#160;</td>
<td class="paramname"><em>attrib_list</em>[]&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>A constructor for creating and initializing a 3D rendering context. </p>
<p>The returned context is created off-screen. It must be attached to a module instance using <code><a class="el" href="classpp_1_1_instance.html#a147a1c1817a7a1fb2b76f5c87ab08899" title="BindGraphics() binds the given graphics as the current display surface.">Instance::BindGraphics</a></code> to draw on the web page.</p>
<p>This constructor is identical to the 2-argument version except that this version allows sharing of resources with another context.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">instance</td><td>The instance that will own the new <a class="el" href="classpp_1_1_graphics3_d.html" title="This class represents a 3D rendering context in the browser.">Graphics3D</a>.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">share_context</td><td>Specifies the context with which all shareable data will be shared. The shareable data is defined by the client API (note that for OpenGL and OpenGL ES, shareable data excludes texture objects named 0). An arbitrary number of <a class="el" href="classpp_1_1_graphics3_d.html" title="This class represents a 3D rendering context in the browser.">Graphics3D</a> resources can share data in this fashion. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">attrib_list</td><td>The list of attributes for the context. See the 2-argument version of this constructor for more information.</td></tr>
</table>
</dd>
</dl>
<p>On failure, the object will be <a class="el" href="classpp_1_1_resource.html#a859068e34cdc2dc0b78754c255323aa9" title="This functions determines if this resource is invalid or uninitialized.">is_null()</a>. </p>
</div>
</div>
<a class="anchor" id="a134128672575294aeb17c263189b9da0"></a><!-- doxytag: member="pp::Graphics3D::~Graphics3D" ref="a134128672575294aeb17c263189b9da0" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classpp_1_1_graphics3_d.html#a134128672575294aeb17c263189b9da0">pp::Graphics3D::~Graphics3D</a> </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Destructor. </p>
</div>
</div>
<hr /><h2>Member Function Documentation</h2>
<a class="anchor" id="ae4527f4526a090c05ab7d9ce9fafb3de"></a><!-- doxytag: member="pp::Graphics3D::GetAttribs" ref="ae4527f4526a090c05ab7d9ce9fafb3de" args="(int32_t attrib_list[]) const " -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t <a class="el" href="classpp_1_1_graphics3_d.html#ae4527f4526a090c05ab7d9ce9fafb3de">pp::Graphics3D::GetAttribs</a> </td>
<td>(</td>
<td class="paramtype">int32_t&#160;</td>
<td class="paramname"><em>attrib_list</em>[]</td><td>)</td>
<td> const</td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_graphics3_d.html#ae4527f4526a090c05ab7d9ce9fafb3de" title="GetAttribs() retrieves the value for each attribute in attrib_list.">GetAttribs()</a> retrieves the value for each attribute in <code>attrib_list</code>. </p>
<p>The list has the same structure as described for the constructor. All attribute values specified in <code>pp_graphics_3d.h</code> can be retrieved.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in,out]</td><td class="paramname">attrib_list</td><td>The list of attributes (name=value pairs) for the context. The list is terminated with <code>PP_GRAPHICS3DATTRIB_NONE</code>.</td></tr>
</table>
</dd>
</dl>
<p>The following error codes may be returned on failure:</p>
<p>PP_ERROR_BADRESOURCE if context is invalid. PP_ERROR_BADARGUMENT if <code>attrib_list</code> is NULL or any attribute in the <code>attrib_list</code> is not a valid attribute.</p>
<p><b>Example:</b></p>
<div class="fragment"><pre class="fragment"> <span class="keywordtype">int</span> attrib_list[] = {PP_GRAPHICS3DATTRIB_RED_SIZE, 0,
PP_GRAPHICS3DATTRIB_GREEN_SIZE, 0,
PP_GRAPHICS3DATTRIB_BLUE_SIZE, 0,
PP_GRAPHICS3DATTRIB_NONE};
<a class="code" href="classpp_1_1_graphics3_d.html#ae4527f4526a090c05ab7d9ce9fafb3de" title="GetAttribs() retrieves the value for each attribute in attrib_list.">GetAttribs</a>(context, attrib_list);
<span class="keywordtype">int</span> red_bits = attrib_list[1];
<span class="keywordtype">int</span> green_bits = attrib_list[3];
<span class="keywordtype">int</span> blue_bits = attrib_list[5];
</pre></div><p>This example retrieves the values for rgb bits in the color buffer. </p>
</div>
</div>
<a class="anchor" id="a21b887529bdba99089ff3c1fa16d3d7c"></a><!-- doxytag: member="pp::Graphics3D::ResizeBuffers" ref="a21b887529bdba99089ff3c1fa16d3d7c" args="(int32_t width, int32_t height)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t <a class="el" href="classpp_1_1_graphics3_d.html#a21b887529bdba99089ff3c1fa16d3d7c">pp::Graphics3D::ResizeBuffers</a> </td>
<td>(</td>
<td class="paramtype">int32_t&#160;</td>
<td class="paramname"><em>width</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t&#160;</td>
<td class="paramname"><em>height</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_graphics3_d.html#a21b887529bdba99089ff3c1fa16d3d7c" title="ResizeBuffers() resizes the backing surface for the context.">ResizeBuffers()</a> resizes the backing surface for the context. </p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">width</td><td>The width of the backing surface. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">height</td><td>The height of the backing surface.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>An int32_t containing <code>PP_ERROR_BADRESOURCE</code> if context is invalid or <code>PP_ERROR_BADARGUMENT</code> if the value specified for width or height is less than zero. <code>PP_ERROR_NOMEMORY</code> might be returned on the next <a class="el" href="classpp_1_1_graphics3_d.html#ae1d1c071bf2737ab310a32558ec5f507" title="SwapBuffers() makes the contents of the color buffer available for compositing.">SwapBuffers()</a> callback if the surface could not be resized due to insufficient resources. </dd></dl>
</div>
</div>
<a class="anchor" id="a504e04ec5f21e324439fe8edc3622957"></a><!-- doxytag: member="pp::Graphics3D::SetAttribs" ref="a504e04ec5f21e324439fe8edc3622957" args="(const int32_t attrib_list[])" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t <a class="el" href="classpp_1_1_graphics3_d.html#a504e04ec5f21e324439fe8edc3622957">pp::Graphics3D::SetAttribs</a> </td>
<td>(</td>
<td class="paramtype">const int32_t&#160;</td>
<td class="paramname"><em>attrib_list</em>[]</td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_graphics3_d.html#a504e04ec5f21e324439fe8edc3622957" title="SetAttribs() sets the values for each attribute in attrib_list.">SetAttribs()</a> sets the values for each attribute in <code>attrib_list</code>. </p>
<p>The list has the same structure as the list used in the constructors.</p>
<p>Attributes that can be specified are:</p>
<ul>
<li>PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR</li>
</ul>
<p>On failure the following error codes may be returned:</p>
<ul>
<li>PP_ERROR_BADRESOURCE if context is invalid.</li>
<li>PP_ERROR_BADARGUMENT if attrib_list is NULL or any attribute in the attrib_list is not a valid attribute. </li>
</ul>
</div>
</div>
<a class="anchor" id="ae1d1c071bf2737ab310a32558ec5f507"></a><!-- doxytag: member="pp::Graphics3D::SwapBuffers" ref="ae1d1c071bf2737ab310a32558ec5f507" args="(const CompletionCallback &amp;cc)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t <a class="el" href="classpp_1_1_graphics3_d.html#ae1d1c071bf2737ab310a32558ec5f507">pp::Graphics3D::SwapBuffers</a> </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classpp_1_1_completion_callback.html">CompletionCallback</a> &amp;&#160;</td>
<td class="paramname"><em>cc</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_graphics3_d.html#ae1d1c071bf2737ab310a32558ec5f507" title="SwapBuffers() makes the contents of the color buffer available for compositing.">SwapBuffers()</a> makes the contents of the color buffer available for compositing. </p>
<p>This function has no effect on off-screen surfaces: surfaces not bound to any module instance. The contents of ancillary buffers are always undefined after calling <a class="el" href="classpp_1_1_graphics3_d.html#ae1d1c071bf2737ab310a32558ec5f507" title="SwapBuffers() makes the contents of the color buffer available for compositing.">SwapBuffers()</a>. The contents of the color buffer are undefined if the value of the <code>PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR</code> attribute of context is not <code>PP_GRAPHICS3DATTRIB_BUFFER_PRESERVED</code>.</p>
<p><a class="el" href="classpp_1_1_graphics3_d.html#ae1d1c071bf2737ab310a32558ec5f507" title="SwapBuffers() makes the contents of the color buffer available for compositing.">SwapBuffers()</a> runs in asynchronous mode. Specify a callback function and the argument for that callback function. The callback function will be executed on the calling thread after the color buffer has been composited with rest of the html page. While you are waiting for a <a class="el" href="classpp_1_1_graphics3_d.html#ae1d1c071bf2737ab310a32558ec5f507" title="SwapBuffers() makes the contents of the color buffer available for compositing.">SwapBuffers()</a> callback, additional calls to <a class="el" href="classpp_1_1_graphics3_d.html#ae1d1c071bf2737ab310a32558ec5f507" title="SwapBuffers() makes the contents of the color buffer available for compositing.">SwapBuffers()</a> will fail.</p>
<p>Because the callback is executed (or thread unblocked) only when the instance's current state is actually on the screen, this function provides a way to rate limit animations. By waiting until the image is on the screen before painting the next frame, you can ensure you're not generating updates faster than the screen can be updated.</p>
<p><a class="el" href="classpp_1_1_graphics3_d.html#ae1d1c071bf2737ab310a32558ec5f507" title="SwapBuffers() makes the contents of the color buffer available for compositing.">SwapBuffers()</a> performs an implicit flush operation on context. If the context gets into an unrecoverable error condition while processing a command, the error code will be returned as the argument for the callback. The callback may return the following error codes:</p>
<p><code>PP_ERROR_NOMEMORY</code> <code>PP_ERROR_CONTEXT_LOST</code></p>
<p>Note that the same error code may also be obtained by calling GetError().</p>
<p>param[in] cc A <code><a class="el" href="classpp_1_1_completion_callback.html" title="This API enables you to implement and receive callbacks when Pepper operations complete asynchronousl...">CompletionCallback</a></code> to be called upon completion of <a class="el" href="classpp_1_1_graphics3_d.html#ae1d1c071bf2737ab310a32558ec5f507" title="SwapBuffers() makes the contents of the color buffer available for compositing.">SwapBuffers()</a>.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>An int32_t containing <code>PP_ERROR_BADRESOURCE</code> if context is invalid or <code>PP_ERROR_BADARGUMENT</code> if callback is invalid. </dd></dl>
</div>
</div>
<hr />The documentation for this class was generated from the following file:<ul>
<li><a class="el" href="graphics__3d_8h.html">graphics_3d.h</a></li>
</ul>
</div><!-- contents -->
</div>
{{/partials.standard_nacl_api}}