chromium/src
0
Fork 0
Code Activity

[NaCl SDK Docs] Only generate one top-level <section> element.

Browse Source 
This fixes the right-side table-of-contents on the documentation page, so it is
collapsible and only shows h2 headings by default.

NOTRY because it is a documentation-only change.

BUG=374811
R=sbc@chromium.org
NOTRY=true

Review URL: https://codereview.chromium.org/438403003

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@287804 0039d316-1c4b-4281-b951-d872f2087c98
This commit is contained in:
binji@chromium.org
2014-08-06 18:01:43 +00:00
parent 4254ae3726
commit c3c19f1925
49 changed files with 128 additions and 712 deletions

26
native_client_sdk/doc_generated/devguide/coding/3D-graphics.html

@@ -13,7 +13,6 @@ with issues directly related to programming in the Native Client
environment. To learn more about OpenGL ES 2.0 itself, see the <a class="reference external" href="http://opengles-book.com/">OpenGL ES 2.0
Programming Guide</a>.
</aside>
<section id="validating-the-client-graphics-platform">
<h2 id="validating-the-client-graphics-platform">Validating the client graphics platform</h2>
<p>Native Client is a software technology that lets you code an application once
and run it on multiple platforms without worrying about the implementation
@@ -25,7 +24,6 @@ to have vulnerabilities that can be exploited.</p>
<p>Even if the GPU driver is safe to use, your program should perform a validation
check before you launch your application to ensure that the driver supports all
the features you need.</p>
<section id="vetting-the-driver-in-javascript">
<h3 id="vetting-the-driver-in-javascript">Vetting the driver in JavaScript</h3>
<p>At startup, the application should perform a few additional tests that can be
implemented in JavaScript on its hosting web page. The script that performs
@@ -36,9 +34,7 @@ can, use the context to confirm the existence of any required OpenGL ES 2.0
extensions. You may want to refer to the <a class="reference external" href="http://www.khronos.org/registry/webgl/extensions/">extension registry</a> and include <a class="reference external" href="https://developer.mozilla.org/en-US/docs/WebGL/Using_Extensions">vendor
prefixes</a>
when checking for extensions.</p>
</section><section id="vetting-the-driver-in-native-client">
<h3 id="vetting-the-driver-in-native-client">Vetting the driver in Native Client</h3>
<section id="create-a-context">
<h4 id="create-a-context">Create a context</h4>
<p>Once you&#8217;ve passed the JavaScript validation tests, it&#8217;s safe to add a Native
Client embed tag to the hosting web page and load the module. As part of the
@@ -50,7 +46,6 @@ the context, try creating a simpler version to see if you&#8217;re asking for an
unsupported feature or exceeding a driver resource limit. Your production code
should always check that the context was created and fail gracefully if that&#8217;s
not the case.</p>
</section><section id="check-for-extensions-and-capabilities">
<h4 id="check-for-extensions-and-capabilities">Check for extensions and capabilities</h4>
<p>Not every GPU supports every extension or has the same amount of texture units,
vertex attributes, etc. On startup, call <code>glGetString(GL_EXTENSIONS)</code> and
@@ -92,7 +87,6 @@ as well as texture and vertex data accordingly:</p>
<code>glGetIntegerv(GL_MAX_TEXTURE_IMAGE_UNITS, ...)</code> returns a value greater
than or equal to the number of simultaneous textures you need.</li>
</ul>
</section></section><section id="vetting-the-driver-in-the-chrome-web-store">
<h3 id="vetting-the-driver-in-the-chrome-web-store">Vetting the driver in the Chrome Web Store</h3>
<p>If you choose to place your application in the <a class="reference external" href="/webstore">Chrome Web Store</a>,
its Web Store <a class="reference external" href="/extensions/manifest">manifest file</a> can include the <code>webgl</code>
@@ -120,7 +114,6 @@ been disabled.&#8221;</p>
<p>The manifest-based check applies only to downloads directly from the Chrome Web
Store. It is not performed when an application is loaded via <a class="reference external" href="/webstore/inline_installation">inline
installation</a>.</p>
</section><section id="what-to-do-when-there-are-problems">
<h3 id="what-to-do-when-there-are-problems">What to do when there are problems</h3>
<p>Using the vetting procedure described above, you should be able to detect the
most common problems before your application runs. If there are problems, your
@@ -131,7 +124,6 @@ might want to linke to the Chrome page that describes <a class="reference extern
<p>If a user can&#8217;t update the driver, or their problem persists, be sure to gather
information about their graphics environment. Ask for the contents of the Chrome
<code>about:gpu</code> page.</p>
</section><section id="document-unreliable-drivers">
<h3 id="document-unreliable-drivers">Document unreliable drivers</h3>
<p>It can be helpful to include information about known dubious drivers in your
user documentation. This might help identify if a rogue driver is the cause of a
@@ -140,7 +132,6 @@ found at the <a class="reference external" href="http://src.chromium.org/viewvc/
and <a class="reference external" href="http://www.khronos.org/webgl/wiki/BlacklistsAndWhitelists">Khronos</a>. You
can use these lists to include information in your documentation that warns
users about dangerous drivers.</p>
</section><section id="test-your-defenses">
<h3 id="test-your-defenses">Test your defenses</h3>
<p>You can test your driver validation code by running Chrome with the following
flags (all at once) and watching how your application responds:</p>
@@ -151,10 +142,8 @@ flags (all at once) and watching how your application responds:</p>
<li><code>--disable-accelerated-compositing</code></li>
<li><code>--disable-accelerated-2d-canvas</code></li>
</ul>
</section></section><section id="calling-opengl-es-2-0-commands">
<h2 id="calling-opengl-es-2-0-commands">Calling OpenGL ES 2.0 commands</h2>
<p>There are three ways to write OpenGL ES 2.0 calls in Native Client.</p>
<section id="use-pure-opengl-es-2-0-function-calls">
<h3 id="use-pure-opengl-es-2-0-function-calls">Use &#8220;pure&#8221; OpenGL ES 2.0 function calls</h3>
<p>You can make OpenGL ES 2.0 calls through a Pepper extension library. The SDK
example <code>examples/api/graphics_3d</code> works this way. In the file
@@ -200,7 +189,6 @@ bool InitGL(int32_t new_width, int32_t new_height) {
necessary: upon application launch (when the graphics context is NULL) and
whenever the module&#8217;s View changes size.</li>
</ul>
</section><section id="use-regal">
<h3 id="use-regal">Use Regal</h3>
<p>If you are porting an OpenGL ES 2.0 application, or are comfortable writing in
OpenGL ES 2.0, you should stick with the Pepper APIs or pure OpenGL ES 2.0 calls
@@ -211,7 +199,6 @@ Client. Regal forwards most OpenGL calls directly to the underlying graphics
library, but it can also emulate other calls that are not included (when
hardware support exists). See <a class="reference external" href="http://www.altdevblogaday.com/2012/09/04/bringing-regal-opengl-to-native-client/">libregal</a>
for more info.</p>
</section><section id="use-the-pepper-api">
<h3 id="use-the-pepper-api">Use the Pepper API</h3>
<p>Your code can call the Pepper PPB_OpenGLES2 API directly, as with any Pepper
interface. When you write in this way, each invocation of an OpenGL ES 2.0
@@ -224,13 +211,11 @@ ppb_g3d_interface-&gt;CompileShader(graphicsContext, shader);
<p>This approach specifically targets the Pepper APIs. Each call corresponds to a
OpenGL ES 2.0 function, but the syntax is unique to Native Client, so the source
file is not portable.</p>
</section></section><section id="implementing-a-rendering-loop">
<h2 id="implementing-a-rendering-loop">Implementing a rendering loop</h2>
<p>Graphics applications require a continuous frame render-and-redraw cycle that
runs at a high frequency. To achieve the best frame rate, is important to
understand how the OpenGL ES 2.0 code in a Native Client module interacts with
Chrome.</p>
<section id="the-chrome-and-native-client-processes">
<h3 id="the-chrome-and-native-client-processes">The Chrome and Native Client processes</h3>
<p>Chrome is a multi-process browser. Each Chrome tab is a separate process that is
running an application with its own main thread (we&#8217;ll call it the Chrome main
@@ -246,7 +231,6 @@ a standstill.</p>
<p>Native Client uses callback functions to synchronize the main threads of the
two processes. Only certain Pepper functions use callbacks; <a class="reference external" href="/native-client/pepper_stable/c/struct_p_p_b___graphics3_d__1__0#a293c6941c0da084267ffba3954793497">SwapBuffers</a>
is one.</p>
</section><section id="swapbuffers-and-its-callback-function">
<h3 id="swapbuffers-and-its-callback-function"><code>SwapBuffers</code> and its callback function</h3>
<p><code>SwapBuffers</code> is non-blocking; it is called from the Native Client thread and
returns immediately. When <code>SwapBuffers</code> is called, it runs asynchronously on
@@ -271,7 +255,6 @@ from the main thread to Native Client, green up-arrows are non-blocking
<code>SwapBuffers</code> calls from Native Client to the main thread. All OpenGL ES 2.0
calls are made from <code>Draw</code> in the Native Client thread.</p>
<img alt="/native-client/images/3d-graphics-render-loop.png" src="/native-client/images/3d-graphics-render-loop.png" />
</section><section id="sdk-example-graphics-3d">
<h3 id="sdk-example-graphics-3d">SDK example <code>graphics_3d</code></h3>
<p>The SDK example <code>graphics_3d</code> uses the function <code>MainLoop</code> (in
<code>hello_world.cc</code>) to create a rendering loop as described above. <code>MainLoop</code>
@@ -293,7 +276,6 @@ void MainLoop(void* foo, int bar) {
}
}
</pre>
</section></section><section id="managing-the-opengl-es-2-0-pipeline">
<h2 id="managing-the-opengl-es-2-0-pipeline">Managing the OpenGL ES 2.0 pipeline</h2>
<p>OpenGL ES 2.0 commands do not run in the Chrome or Native Client processes. They
are passed into a FIFO queue in shared memory which is best understood as a <a class="reference external" href="http://www.chromium.org/developers/design-documents/gpu-command-buffer">GPU
@@ -324,7 +306,6 @@ commands. For example, issue a flush before you begin any multithreaded particle
work, so that the command buffer will be clear when you start doing OpenGL ES
2.0 calls again. Determining where and how often to call <code>glFlush</code> can be
tricky, you will need to experiment to find the sweet spot.</p>
</section><section id="rendering-and-inactive-tabs">
<h2 id="rendering-and-inactive-tabs">Rendering and inactive tabs</h2>
<p>Users will often switch between tabs in a multi-tab browser. A well-behaved
application that&#8217;s performing 3D rendering should pause any real-time processing
@@ -347,7 +328,6 @@ main thread every 30 msec or so. This provides time to update features that
should still run in the background, like audio. It may also be helpful to call
<code>sched_yield</code> or <code>usleep</code> on any worker threads to release resources and
cede cycles to the OS.</p>
<section id="handling-tab-activation-from-the-main-thread">
<h3 id="handling-tab-activation-from-the-main-thread">Handling tab activation from the main thread</h3>
<p>You can detect and respond to the activation or deactivation of a tab with
JavaScript on your hosting page. Add an EventListener for <code>visibilitychange</code>
@@ -364,7 +344,6 @@ document.addEventListener('visibilitychange', function(){
}, false);
</pre>
</section><section id="handling-tab-activation-from-the-native-client-thread">
<h3 id="handling-tab-activation-from-the-native-client-thread">Handling tab activation from the Native Client thread</h3>
<p>You can also detect and respond to the activation or deactivation of a tab
directly from your Native Client module by including code in the function
@@ -372,11 +351,9 @@ directly from your Native Client module by including code in the function
module&#8217;s view occurs. The code can call <code>ppb::View::IsPageVisible</code> to
determine if the page is visible or not. The most common cause of invisible
pages is that the page is in a background tab.</p>
</section></section><section id="tips-and-best-practices">
<h2 id="tips-and-best-practices">Tips and best practices</h2>
<p>Here are some suggestions for writing safe code and getting the maximum
performance with the Pepper 3D API.</p>
<section id="do-s">
<h3 id="do-s">Do&#8217;s</h3>
<ul class="small-gap">
<li><p class="first"><strong>Make sure to enable attrib 0.</strong> OpenGL requires that you enable attrib 0,
@@ -408,7 +385,6 @@ transforms, avoid matrix-to-matrix conversions. For instance, upres a vec3 to
a vec4 before transforming it by a mat4, rather than converting the mat4 to a
mat3.</li>
</ul>
</section><section id="don-ts">
<h3 id="don-ts">Don&#8217;ts</h3>
<ul class="small-gap">
<li><strong>Don&#8217;t use client side buffers.</strong> OpenGL ES 2.0 can use client side data with
@@ -436,6 +412,6 @@ avoid this problem, keep static and dynamic data in different buffers.</li>
error. Each time it is called, an error messages will appear in Chrome&#8217;s
<code>about:gpu</code> tab.</li>
</ul>
</section></section></section>
</section>
{{/partials.standard_nacl_article}}

11
native_client_sdk/doc_generated/devguide/coding/application-structure.html

@@ -19,7 +19,6 @@ The &#8220;Hello, World&#8221; example is used here to illustrate basic
Native Client programming techniques. You can find this code in the
<em>/getting_started/part1</em> directory in the Native Client SDK download.
</aside>
<section id="application-components">
<h2 id="application-components">Application components</h2>
<p>A Native Client application typically contains the following components:</p>
<ul class="small-gap">
@@ -37,8 +36,7 @@ architecture-specific executable files (with .nexe extensions).</li>
<p>Applications that are published in the <a class="reference external" href="https://chrome.google.com/webstore/search?q=%22Native+Client%22+OR+NativeClient+OR+NaCl">Chrome Web Store</a>
also include a Chrome
Web Store manifest file <code>(manifest.json)</code> and one or more icon files.</p>
</section><section id="html-file-and-the-embed-element">
<span id="html-file"></span><h2 id="html-file-and-the-embed-element"><span id="html-file"></span>HTML file and the &lt;embed&gt; element</h2>
<h2 id="html-file-and-the-embed-element"><span id="html-file"></span>HTML file and the &lt;embed&gt; element</h2>
<p>The <code>&lt;embed&gt;</code> element in an HTML file triggers the loading of a Native Client
module and specifies the rectangle on the web page that is managed by the
module. Here is the &lt;embed&gt; element from the &#8220;Hello, World&#8221; application:</p>
@@ -68,8 +66,7 @@ user&#8217;s computer (see the following section for more information)</dd>
modules the type must be &#8220;application/x-pnacl&#8221;. For architecture-specific
Native Client modules the type must be &#8220;application/x-nacl&#8221;</dd>
</dl>
</section><section id="manifest-files">
<span id="manifest-file"></span><h2 id="manifest-files"><span id="manifest-file"></span>Manifest Files</h2>
<h2 id="manifest-files"><span id="manifest-file"></span>Manifest Files</h2>
<p>Native Client applications have two types of manifest files: a Chrome Web Store
manifest file and a Native Client manifest file.</p>
<p>A <strong>Chrome Web Store manifest file</strong> is a file with information about a web
@@ -132,7 +129,6 @@ manifest files.</p>
compilation step (see the Makefile in any of the SDK examples for an
illustration of how to do so). The manifest file format is also
<a class="reference internal" href="/native-client/reference/nacl-manifest-format.html"><em>documented</em></a>.</p>
</section><section id="modules-and-instances">
<h2 id="modules-and-instances">Modules and instances</h2>
<p>A Native Client <strong>module</strong> is C or C++ code compiled into a PNaCl .pexe file or
a NaCl .nexe file.</p>
@@ -146,7 +142,6 @@ module may be included in a web page multiple times by using multiple
<code>&lt;embed&gt;</code> elements that refer to the module; in this case the Native Client
runtime system loads the module once and creates multiple instances that are
managed by the module.</p>
</section><section id="native-client-modules-a-closer-look">
<h2 id="native-client-modules-a-closer-look">Native Client modules: A closer look</h2>
<p>A Native Client module must include three components:</p>
<ul class="small-gap">
@@ -212,6 +207,6 @@ issue a <code>crash</code> event
samples shown above don&#8217;t actually do anything. Subsequent chapters in the
Developer&#8217;s Guide build on these code samples and add more interesting
functionality.</p>
</section></section>
</section>
{{/partials.standard_nacl_article}}

14
native_client_sdk/doc_generated/devguide/coding/audio.html

@@ -38,7 +38,6 @@ starts playing the audio samples as soon as it is loaded into the browser. For a
slightly more sophisticated example, see the <code>audio</code> example (source code in
the SDK directory <code>examples/api/audio</code>), which lets users specify a frequency
for the sine wave and click buttons to start and stop audio playback.</p>
<section id="reference-information">
<h2 id="reference-information">Reference information</h2>
<p>For reference information related to the Pepper audio API, see the following
documentation:</p>
@@ -49,7 +48,6 @@ documentation:</p>
<li><a class="reference external" href="/native-client/pepper_stable/cpp/audio_8h">audio.h</a></li>
<li><a class="reference external" href="/native-client/pepper_stable/c/group___enums#gaee750c350655f2fb0fe04c04029e0ff8">PP_AudioSampleRate</a></li>
</ul>
</section><section id="about-the-pepper-audio-api">
<h2 id="about-the-pepper-audio-api">About the Pepper audio API</h2>
<p>The Pepper audio API lets Native Client modules play audio streams in a
browser. To play an audio stream, a module generates audio samples and writes
@@ -81,7 +79,6 @@ audio buffer.</li>
<p>This basic interaction is illustrated below, and described in detail in the
sections that follow.</p>
<img alt="/native-client/images/pepper-audio-api.png" src="/native-client/images/pepper-audio-api.png" />
</section><section id="digital-audio-concepts">
<h2 id="digital-audio-concepts">Digital audio concepts</h2>
<p>Before you use the Pepper audio API, it&#8217;s helpful to understand a few concepts
that are fundamental to how digital audio is recorded and played back:</p>
@@ -110,7 +107,6 @@ with the following configurations:</p>
<li><strong>bit depth</strong>: 16</li>
<li><strong>channels</strong>: 2 (stereo)</li>
</ul>
</section><section id="setting-up-the-module">
<h2 id="setting-up-the-module">Setting up the module</h2>
<p>The code examples below describe a simple Native Client module that generates
audio samples using a sine wave with a frequency of 440 Hz. The module starts
@@ -153,9 +149,7 @@ class SineSynthModule : public pp::Module {
}
};
</pre>
</section><section id="creating-an-audio-configuration-resource">
<h2 id="creating-an-audio-configuration-resource">Creating an audio configuration resource</h2>
<section id="resources">
<h3 id="resources">Resources</h3>
<p>Before the module can play an audio stream, it must create two resources: an
audio configuration resource and an audio resource. Resources are handles to
@@ -166,7 +160,6 @@ when the samples in the stream&#8217;s buffer run out. An audio configuration re
is an object that stores configuration data for an audio resource, including the
sampling frequency of the audio samples, and the number of samples that the
callback function must provide when the browser invokes it.</p>
</section><section id="sample-frame-count">
<h3 id="sample-frame-count">Sample frame count</h3>
<p>Prior to creating an audio configuration resource, the module should call
<code>RecommendSampleFrameCount</code> to obtain a <em>sample frame count</em> from the
@@ -192,7 +185,6 @@ the browser must invoke the callback function frequently to refill the audio
buffer. Conversely, a large sample frame count results in higher latency but
lower CPU usage. You should request a large sample frame count if your module
will play long, uninterrupted audio segments.</p>
</section><section id="supported-audio-configurations">
<h3 id="supported-audio-configurations">Supported audio configurations</h3>
<p>After the module obtains a sample frame count, it can create an audio
configuration resource. Currently the Pepper audio API supports audio streams
@@ -225,14 +217,12 @@ bool SineSynthInstance::Init(uint32_t argc,
return audio_.StartPlayback();
}
</pre>
</section></section><section id="creating-an-audio-resource">
<h2 id="creating-an-audio-resource">Creating an audio resource</h2>
<p>Once the module has created an audio configuration resource, it can create an
audio resource. To do so, it instantiates a <code>pp::Audio</code> object, passing in a
pointer to the module instance, the audio configuration resource, a callback
function, and a pointer to user data (data that is used in the callback
function). See the example above.</p>
</section><section id="implementing-a-callback-function">
<h2 id="implementing-a-callback-function">Implementing a callback function</h2>
<p>The browser calls the callback function associated with an audio resource every
time it needs more samples to play. The callback function can generate new
@@ -293,7 +283,6 @@ class SineSynthInstance : public pp::Instance {
...
};
</pre>
<section id="application-threads-and-real-time-requirements">
<h3 id="application-threads-and-real-time-requirements">Application threads and real-time requirements</h3>
<p>The callback function runs in a background application thread. This allows audio
processing to continue even when the application is busy doing something
@@ -325,7 +314,6 @@ callback function may not be called immediately after the call to
another thread so that the audio stream starts playing simultaneously with
another action in your application, you must handle such synchronization
manually.</p>
</section></section><section id="starting-and-stopping-playback">
<h2 id="starting-and-stopping-playback">Starting and stopping playback</h2>
<p>To start and stop audio playback, the module simply reacts to JavaScript
messages.</p>
@@ -347,6 +335,6 @@ void SineSynthInstance::HandleMessage(const pp::Var&amp; var_message) {
}
}
</pre>
</section></section>
</section>
{{/partials.standard_nacl_article}}

26
native_client_sdk/doc_generated/devguide/coding/file-io.html

@@ -35,8 +35,7 @@
</li>
</ul>
</div><section id="introduction">
<h2 id="introduction">Introduction</h2>
</div><h2 id="introduction">Introduction</h2>
<p>This chapter describes how to use the <a class="reference external" href="/native-client/pepper_stable/cpp/classpp_1_1_file_i_o">FileIO API</a> to read and write
files using a local secure data store.</p>
<p>You might use the File IO API with the URL Loading APIs to create an overall
@@ -53,7 +52,6 @@ application.</li>
</ol>
<p>The example discussed in this chapter is included in the SDK in the directory
<code>examples/api/file_io</code>.</p>
</section><section id="reference-information">
<h2 id="reference-information">Reference information</h2>
<p>For reference information related to FileIO, see the following documentation:</p>
<ul class="small-gap">
@@ -64,7 +62,6 @@ a file reference or &#8220;weak pointer&#8221; to a file in a file system</li>
<li><a class="reference external" href="/native-client/pepper_stable/cpp/file__system_8h">file_system.h</a> - API to
create a file system associated with a file</li>
</ul>
</section><section id="local-file-i-o">
<h2 id="local-file-i-o">Local file I/O</h2>
<p>Chrome provides an obfuscated, restricted area on disk to which a web app can
safely <a class="reference external" href="https://developers.google.com/chrome/whitepapers/storage#persistent">read and write files</a>. The
@@ -74,8 +71,7 @@ files and manage caching yourself. The data is persistent between launches of
Chrome, and is not removed unless your application deletes it or the user
manually deletes it. There is no limit to the amount of local data you can
use, other than the actual space available on the local drive.</p>
<section id="enabling-local-file-i-o">
<span id="enabling-file-access"></span><span id="quota-management"></span><h3 id="enabling-local-file-i-o"><span id="enabling-file-access"></span><span id="quota-management"></span>Enabling local file I/O</h3>
<h3 id="enabling-local-file-i-o"><span id="enabling-file-access"></span><span id="quota-management"></span>Enabling local file I/O</h3>
<p>The easiest way to enable the writing of persistent local data is to include
the <a class="reference external" href="/extensions/declare_permissions#unlimitedStorage">unlimitedStorage permission</a> in your Chrome Web Store
manifest file. With this permission you can use the Pepper FileIO API without
@@ -86,7 +82,6 @@ JavaScript code that calls the <a class="reference external" href="http://update
explicitly request local disk space before using the FileIO API. In this case
Chrome will prompt the user to accept a requestQuota call every time one is
made.</p>
</section><section id="testing-local-file-i-o">
<h3 id="testing-local-file-i-o">Testing local file I/O</h3>
<p>You should be aware that using the <code>unlimitedStorage</code> manifest permission
constrains the way you can test your app. Three of the four techniques
@@ -97,7 +92,6 @@ If you want to test the file IO portion of your app with a simple local server,
you need to include JavaScript code that calls the HTML5 Quota Management API.
When you deliver your application you can replace this code with the
<code>unlimitedStorage</code> manifest permission.</p>
</section></section><section id="the-file-io-example">
<h2 id="the-file-io-example">The <code>file_io</code> example</h2>
<p>The Native Client SDK includes an example, <code>file_io</code>, that demonstrates how
to read and write a local disk file. Since you will probably run the example
@@ -115,7 +109,6 @@ Native Client module.</li>
</ul>
<p>The remainder of this section covers the code in the <code>file_io.cc</code> file for
reading and writing files.</p>
<section id="file-i-o-overview">
<h3 id="file-i-o-overview">File I/O overview</h3>
<p>Like many Pepper APIs, the File IO API includes a set of methods that execute
asynchronously and that invoke callback functions in your Native Client module.
@@ -129,7 +122,6 @@ your worker thread, so you can use the stack and standard control flow
structures normally.</p>
<p>The high-level flow for the <code>file_io</code> example is described below. Note that
methods in the namespace <code>pp</code> are part of the Pepper C++ API.</p>
</section><section id="creating-and-writing-a-file">
<h3 id="creating-and-writing-a-file">Creating and writing a file</h3>
<p>Following are the high-level steps involved in creating and writing to a
file:</p>
@@ -142,7 +134,6 @@ blocked until the call to <code>Write</code> completes. If there is more data to
write, <code>Write</code> is called again.</li>
<li>When there is no more data to write, call <code>pp::FileIO::Flush</code>.</li>
</ol>
</section><section id="opening-and-reading-a-file">
<h3 id="opening-and-reading-a-file">Opening and reading a file</h3>
<p>Following are the high-level steps involved in opening and reading a file:</p>
<ol class="arabic simple">
@@ -155,15 +146,12 @@ its file size. The thread is blocked until <code>Query</code> completes.</li>
until <code>Read</code> completes. If there is more data to read, <code>Read</code> is called
again.</li>
</ol>
</section><section id="deleting-a-file">
<h3 id="deleting-a-file">Deleting a file</h3>
<p>Deleting a file is straightforward: call <code>pp::FileRef::Delete</code>. The thread is
blocked until <code>Delete</code> completes.</p>
</section><section id="making-a-directory">
<h3 id="making-a-directory">Making a directory</h3>
<p>Making a directory is also straightforward: call <code>pp::File::MakeDirectory</code>.
The thread is blocked until <code>MakeDirectory</code> completes.</p>
</section><section id="listing-the-contents-of-a-directory">
<h3 id="listing-the-contents-of-a-directory">Listing the contents of a directory</h3>
<p>Following are the high-level steps involved in listing a directory:</p>
<ol class="arabic simple">
@@ -175,7 +163,6 @@ its callback, so it must be specified.</li>
<code>ListCallback</code> which packages up the results into a string message, and
sends it to JavaScript.</li>
</ol>
</section></section><section id="file-io-deep-dive">
<h2 id="file-io-deep-dive"><code>file_io</code> deep dive</h2>
<p>The <code>file_io</code> example displays a user interface with a couple of fields and
several buttons. Following is a screenshot of the <code>file_io</code> example:</p>
@@ -185,7 +172,6 @@ default values for filenames. Try typing a message in the large input box and
clicking <code>Save</code>, then switching to the <code>Load File</code> operation, and
clicking <code>Load</code>.</p>
<p>Let&#8217;s take a look at what is going on under the hood.</p>
<section id="opening-a-file-system-and-preparing-for-file-i-o">
<h3 id="opening-a-file-system-and-preparing-for-file-i-o">Opening a file system and preparing for file I/O</h3>
<p><code>pp::Instance::Init</code> is called when an instance of a module is created. In
this example, <code>Init</code> starts a new thread (via the <code>pp::SimpleThread</code>
@@ -226,7 +212,6 @@ void OpenFileSystem(int32_t /*result*/) {
}
}
</pre>
</section><section id="handling-messages-from-javascript">
<h3 id="handling-messages-from-javascript">Handling messages from JavaScript</h3>
<p>When you click the <code>Save</code> button, JavaScript posts a message to the NaCl
module with the file operation to perform sent as a string (See <a class="reference internal" href="/native-client/devguide/coding/message-system.html"><em>Messaging
@@ -260,7 +245,6 @@ virtual void HandleMessage(const pp::Var&amp; var_message) {
}
}
</pre>
</section><section id="saving-a-file">
<h3 id="saving-a-file">Saving a file</h3>
<p><code>FileIoInstance::Save</code> is called when the <code>Save</code> button is pressed. First,
it checks to see that the FileSystem has been successfully opened:</p>
@@ -324,7 +308,6 @@ if (flush_result != PP_OK) {
return;
}
</pre>
</section><section id="loading-a-file">
<h3 id="loading-a-file">Loading a file</h3>
<p><code>FileIoInstance::Load</code> is called when the <code>Load</code> button is pressed. Like
the <code>Save</code> function, <code>Load</code> first checks to see if the FileSystem has been
@@ -394,7 +377,6 @@ std::string string_data(data.begin(), data.end());
PostMessage(&quot;DISP|&quot; + string_data);
ShowStatusMessage(&quot;Load success&quot;);
</pre>
</section><section id="id1">
<h3 id="id1">Deleting a file</h3>
<p><code>FileIoInstance::Delete</code> is called when the <code>Delete</code> button is pressed.
First, it checks whether the FileSystem has been opened, and creates a new
@@ -420,7 +402,6 @@ if (result == PP_ERROR_FILENOTFOUND) {
return;
}
</pre>
</section><section id="listing-files-in-a-directory">
<h3 id="listing-files-in-a-directory">Listing files in a directory</h3>
<p><code>FileIoInstance::List</code> is called when the <code>List Directory</code> button is
pressed. Like all other operations, it checks whether the FileSystem has been
@@ -470,7 +451,6 @@ void ListCallback(int32_t result,
ShowStatusMessage(&quot;List success&quot;);
}
</pre>
</section><section id="making-a-new-directory">
<h3 id="making-a-new-directory">Making a new directory</h3>
<p><code>FileIoInstance::MakeDir</code> is called when the <code>Make Directory</code> button is
pressed. Like all other operations, it checks whether the FileSystem has been
@@ -492,6 +472,6 @@ if (result != PP_OK) {
}
ShowStatusMessage(&quot;Make directory success&quot;);
</pre>
</section></section></section>
</section>
{{/partials.standard_nacl_article}}

20
native_client_sdk/doc_generated/devguide/coding/message-system.html

@@ -43,7 +43,6 @@ The &#8220;Hello, World&#8221; example for getting started with NaCl is used her
illustrate basic programming techniques. You can find this code in
the <code>/getting_started/part2</code> directory in the Native Client SDK download.
</aside>
<section id="reference-information">
<h2 id="reference-information">Reference information</h2>
<p>For reference information related to the Pepper messaging API, see the
following documentation:</p>
@@ -53,7 +52,6 @@ HandleMessage(), PostMessage())</li>
<li><a class="reference external" href="/native-client/pepper_stable/cpp/classpp_1_1_module">pp::Module class</a></li>
<li><a class="reference external" href="/native-client/pepper_stable/cpp/classpp_1_1_var">pp::Var class</a></li>
</ul>
</section><section id="introduction-to-the-messaging-system">
<h2 id="introduction-to-the-messaging-system">Introduction to the messaging system</h2>
<p>Native Client modules and JavaScript communicate by sending messages to each
other. The most basic form of a message is a string. Messages support many
@@ -81,7 +79,6 @@ messages are:</p>
</ul>
<p>If you want to receive messages from JavaScript, you need to implement the
<code>pp::Instance::HandleMessage()</code> function in your Native Client module.</p>
<section id="design-of-the-messaging-system">
<h3 id="design-of-the-messaging-system">Design of the messaging system</h3>
<p>The Native Client messaging system is analogous to the system used by
the browser to allow web workers to communicate (see the <a class="reference external" href="http://www.w3.org/TR/workers">W3 web
@@ -103,12 +100,10 @@ avoiding the following problems:</p>
than a few moments.</li>
<li>The application hangs while waiting for an unresponsive Native Client module.</li>
</ul>
</section></section><section id="communication-tasks-in-the-hello-world-example">
<h2 id="communication-tasks-in-the-hello-world-example">Communication tasks in the &#8220;Hello, World&#8221; example</h2>
<p>The following sections describe how the &#8220;Hello, World&#8221; example posts
and handles messages on both the JavaScript side and the Native Client
side of the application.</p>
<section id="javascript-code">
<h3 id="javascript-code">JavaScript code</h3>
<p>The JavaScript code and HTML in the &#8220;Hello, World&#8221; example can be
found in the <code>example.js</code>, <code>common.js</code>, and <code>index.html</code> files.
@@ -121,7 +116,6 @@ incoming <code>message</code> events.</li>
<li>Calls <code>postMessage()</code> to communicate with the NaCl module,
after the page loads.</li>
</ol>
<section id="step-1-from-common-js">
<h4 id="step-1-from-common-js">Step 1: From common.js</h4>
<pre class="prettyprint">
function attachDefaultListeners() {
@@ -134,7 +128,6 @@ function attachDefaultListeners() {
// ...
}
</pre>
</section><section id="step-2-from-example-js">
<h4 id="step-2-from-example-js">Step 2: From example.js</h4>
<pre class="prettyprint">
// This function is called by common.js when a message is received from the
@@ -152,7 +145,6 @@ function handleMessage(message) {
&lt;div id=&quot;log&quot;&gt;&lt;/div&gt;
&lt;/body&gt;
</pre>
</section><section id="step-3-from-example-js">
<h4 id="step-3-from-example-js">Step 3: From example.js</h4>
<pre class="prettyprint">
// From example.js, Step 3:
@@ -164,7 +156,6 @@ function moduleDidLoad() {
common.naclModule.postMessage('hello');
}
</pre>
</section></section><section id="native-client-module">
<h3 id="native-client-module">Native Client module</h3>
<p>The C++ code in the Native Client module of the &#8220;Hello, World&#8221; example:</p>
<ol class="arabic simple">
@@ -201,16 +192,13 @@ class HelloTutorialInstance : public pp::Instance {
}
};
</pre>
</section></section><section id="messaging-in-javascript-code-more-details">
<h2 id="messaging-in-javascript-code-more-details">Messaging in JavaScript code: More details.</h2>
<p>This section describes in more detail the messaging system code in the
JavaScript portion of the &#8220;Hello, World&#8221; example.</p>
<section id="setting-up-an-event-listener-and-handler">
<h3 id="setting-up-an-event-listener-and-handler">Setting up an event listener and handler</h3>
<p>The following JavaScript code sets up an event listener for messages
posted by the Native Client module. It then defines a message handler
that simply logs the content of messages received from the module.</p>
<section id="setting-up-the-message-handler-on-load">
<h4 id="setting-up-the-message-handler-on-load">Setting up the &#8216;message&#8217; handler on load</h4>
<pre class="prettyprint">
// From common.js
@@ -244,7 +232,6 @@ function attachDefaultListeners() {
// ...
}
</pre>
</section><section id="implementing-the-handler">
<h4 id="implementing-the-handler">Implementing the handler</h4>
<pre class="prettyprint">
// From example.js
@@ -256,11 +243,9 @@ function handleMessage(message) {
<p>Note that the <code>handleMessage()</code> function is handed a message_event
containing <code>data</code> that you can display or manipulate in JavaScript. The
&#8220;Hello, World&#8221; application simply logs this data to the <code>log</code> div.</p>
</section></section></section><section id="messaging-in-the-native-client-module-more-details">
<h2 id="messaging-in-the-native-client-module-more-details">Messaging in the Native Client module: More details.</h2>
<p>This section describes in more detail the messaging system code in
the Native Client module portion of the &#8220;Hello, World&#8221; example.</p>
<section id="implementing-handlemessage">
<h3 id="implementing-handlemessage">Implementing HandleMessage()</h3>
<p>If you want the Native Client module to receive and handle messages
from JavaScript, you need to implement a <code>HandleMessage()</code> function
@@ -301,7 +286,6 @@ class HelloTutorialInstance : public pp::Instance {
}
};
</pre>
</section><section id="implementing-application-specific-functions">
<h3 id="implementing-application-specific-functions">Implementing application-specific functions</h3>
<p>While the &#8220;Hello, World&#8221; example is very simple, your Native Client
module will likely include application-specific functions to perform
@@ -316,7 +300,6 @@ character to determine which command to execute. If the command is
command is &#8220;uncompress&#8221;, then data to process is an already-compressed
string. After processing the data asynchronously, the application then
returns the result to JavaScript.</p>
</section><section id="sending-messages-back-to-the-javascript-code">
<h3 id="sending-messages-back-to-the-javascript-code">Sending messages back to the JavaScript code</h3>
<p>The Native Client module sends messages back to the JavaScript code
using <code>PostMessage()</code>. The Native Client module always returns
@@ -326,7 +309,6 @@ end of the Native Client module&#8217;s <code>HandleMessage()</code> function:</
<pre class="prettyprint">
PostMessage(var_reply);
</pre>
</section><section id="sending-and-receiving-other-pp-var-types">
<h3 id="sending-and-receiving-other-pp-var-types">Sending and receiving other <code>pp::Var</code> types</h3>
<p>Besides strings, <code>pp::Var</code> can represent other types of JavaScript
objects. For example, messages can be JavaScript objects. These
@@ -370,6 +352,6 @@ virtual void HandleMessage(const pp::Var&amp; var) {
}
}
</pre>
</section></section></section>
</section>
{{/partials.standard_nacl_article}}

13
native_client_sdk/doc_generated/devguide/coding/nacl_io.html

@@ -15,8 +15,7 @@
<li><a class="reference internal" href="#reference-information" id="id6">Reference information</a></li>
</ul>
</div><section id="introduction">
<h2 id="introduction">Introduction</h2>
</div><h2 id="introduction">Introduction</h2>
<p><code>nacl_io</code> is a utility library that provides implementations of standard
C APIs such as POSIX I/O (<code>stdio.h</code>) and BSD sockets (<code>sys/socket.h</code>).
Its primary function is to allow code that uses these standard APIs to be
@@ -58,7 +57,6 @@ types which are described in the table below:</p>
</tr>
</tbody>
</table>
</section><section id="using-nacl-io">
<h2 id="using-nacl-io">Using nacl_io</h2>
<p>Using nacl_io is mostly just a matter of using the standard POSIX C library
functions. However, there are some steps required to initialize the library
@@ -79,9 +77,7 @@ options are explained in the <a class="reference internal" href="/native-client/
thread. This is because the main Pepper thread does not support the blocking
behavior needed by the POSIX I/O operations.</li>
</ol>
</section><section id="the-nacl-io-demo">
<h2 id="the-nacl-io-demo">The nacl_io demo</h2>
<section id="building-and-running-the-demo">
<h3 id="building-and-running-the-demo">Building and running the demo</h3>
<p>The demo application launches a Native Client module that mounts three file
systems and displays a set of controls that let you work with them:</p>
@@ -116,10 +112,8 @@ in the menu, and press the fclose button</li>
<li>select the fread command, be sure the file /persistent/test is selected in
the menu, enter a byte count, and press the fread button</li>
</ol>
</section><section id="a-look-at-the-code">
<h3 id="a-look-at-the-code">A look at the code</h3>
<p>The demo is written C and comprises three files.</p>
<section id="nacl-io-demo-c">
<h4 id="nacl-io-demo-c">nacl_io_demo.c</h4>
<p>This is the demo&#8217;s main file. The code here creates and initializes the Native
Client module instance. The Pepper function <code>Instance_DidCreate</code> initializes
@@ -164,14 +158,12 @@ function domContentLoaded(name, tc, config, width, height) {
messages sent from the html page and performs the specified file system
operations. The logic for the worker thread is encoded in the other two files,
described below.</p>
</section><section id="queue-c">
<h4 id="queue-c">queue.c</h4>
<p>This file implements a circular queue that is used to receive messages from the
browser UI to the Native Client module. The file system commands in the
enqueued messages are executed on the worker thread. This keeps blocking calls
(like fread) off the main Native Client thread, which is a good thing. The
queue is initialized in nacl_io_demo.c <code>Instance_DidCreate</code>.</p>
</section><section id="handlers-c">
<h4 id="handlers-c">handlers.c</h4>
<p>This file implements the stdio calls associated with the commands sent from the
browser. There is a separate <code>Handle*</code> function for each command: fopen,
@@ -211,7 +203,6 @@ int HandleFwrite(int num_params, char** params, char** output) {
return 0;
}
</pre>
</section></section></section><section id="reference-information">
<h2 id="reference-information">Reference information</h2>
<p>The example discussed here is included in the SDK in the directory
<code>examples/demo/nacl_io_demo</code>.</p>
@@ -220,6 +211,6 @@ Pepper API. For reference information related to the nacl_io interface see
its header file in the SDK directory, located at
<code>include/nacl_io/nacl_io.h</code>.</p>
<p>For more about the HTML5 file system read the <a class="reference external" href="http://dev.w3.org/2009/dap/file-system/pub/FileSystem/">specification</a>.</p>
</section></section>
</section>
{{/partials.standard_nacl_article}}

7
native_client_sdk/doc_generated/devguide/coding/native-client-modules.html

@@ -13,14 +13,12 @@ but depend on whether the module is written in C or C++.</p>
<li><a class="reference internal" href="#id1" id="id4">Writing modules in C++</a></li>
</ul>
</div><section id="introduction">
<h2 id="introduction">Introduction</h2>
</div><h2 id="introduction">Introduction</h2>
<p>Native Client modules do not have a <code>main()</code> function. When a module loads,
the Native Client runtime calls the code in the module to create an instance and
initialize the interfaces for the APIs the module uses. This initialization
sequence depends on whether the module is written in C or C++ and requires that
you implement specific functions in each case.</p>
</section><section id="writing-modules-in-c">
<h2 id="writing-modules-in-c">Writing modules in C</h2>
<p>The C API uses a prefix convention to show whether an interface is implemented
in the browser or in a module. Interfaces starting with <code>PPB_</code> (which can be
@@ -111,7 +109,6 @@ PP_EXPORT int32_t PPP_InitializeModule(PP_Module a_module_id, PPB_GetInterface g
return PP_OK;
}
</pre>
</section><section id="id1">
<h2 id="id1">Writing modules in C++</h2>
<p>When you implement a Native Client module in C++ you must include these components:</p>
<ul class="small-gap">
@@ -173,6 +170,6 @@ how to send messages between JavaScript code and Native Client modules.</p>
samples shown above don&#8217;t actually do anything. Subsequent documents in the
Developer&#8217;s Guide build on these code samples and add more interesting
functionality.</p>
</section></section>
</section>
{{/partials.standard_nacl_article}}

8
native_client_sdk/doc_generated/devguide/coding/progress-events.html

@@ -23,7 +23,6 @@ The load_progress example illustrates progress event handling. You can find
this code in the <code>/examples/tutorial/load_progress/</code> directory in the Native
Client SDK download.
</aside>
<section id="module-loading-and-progress-events">
<h2 id="module-loading-and-progress-events">Module loading and progress events</h2>
<p>The Native Client runtime reports a set of state changes during the module
loading process by means of DOM progress events. This set of events is a direct
@@ -257,7 +256,6 @@ illegal.</td>
</table>
<p>Errors that occur during loading are logged to the JavaScript console in Google
Chrome (select the menu icon <img alt="menu-icon" src="/native-client/images/menu-icon.png" /> &gt; Tools &gt; JavaScript console).</p>
</section><section id="handling-progress-events">
<h2 id="handling-progress-events">Handling progress events</h2>
<p>You should add event listeners in a <code>&lt;script&gt;</code> element to listen for these
events before the <code>&lt;embed&gt;</code> element is parsed. For example, the following code
@@ -299,7 +297,6 @@ listeners on outer elements (including the <code>&lt;body&gt;</code> element) to
from inner elements. For more information, see the W3 specifications for <a class="reference external" href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-flow-capture">event
flow capture</a> and
<a class="reference external" href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-registration">event listener registration</a>.</p>
</section><section id="displaying-load-status">
<h2 id="displaying-load-status">Displaying load status</h2>
<p>One common response to progress events is to display the percentage of the
module that has been loaded. In the load_progress example, when the <code>progress</code>
@@ -323,7 +320,6 @@ function moduleLoadProgress(event) {
}
}
</pre>
</section><section id="the-lasterror-attribute">
<h2 id="the-lasterror-attribute">The <code>lastError</code> attribute</h2>
<p>The <code>&lt;embed&gt;</code> element has a <code>lastError</code> attribute that is set to an
informative string whenever a load failure (an <code>error</code> or <code>abort</code> event)
@@ -346,7 +342,6 @@ function moduleLoadError() {
common.logMessage('error: ' + common.naclModule.lastError);
}
</pre>
</section><section id="the-readystate-attribute">
<h2 id="the-readystate-attribute">The <code>readyState</code> attribute</h2>
<p>You can use the <code>readyState</code> attribute to monitor the loading process. This
attribute is particularly useful if you don&#8217;t care about the details of
@@ -413,7 +408,6 @@ the progress events are generated.</p>
&lt;/body&gt;
&lt;/html&gt;
</pre>
</section><section id="the-exitstatus-attribute">
<h2 id="the-exitstatus-attribute">The <code>exitStatus</code> attribute</h2>
<p>This read-only attribute is set if the application calls <code>exit(n)</code>,
<code>abort()</code>, or crashes. Since NaCl modules are event handlers, there is no
@@ -429,6 +423,6 @@ target architecture, and may change in the future. Applications should not
rely on the <code>exitStatus</code> value being stable in these cases, but the value
may nevertheless be useful for temporary debugging.</li>
</ul>
</section></section>
</section>
{{/partials.standard_nacl_api}}

13
native_client_sdk/doc_generated/devguide/coding/url-loading.html

@@ -21,13 +21,11 @@
</li>
</ul>
</div><section id="introduction">
<h2 id="introduction">Introduction</h2>
</div><h2 id="introduction">Introduction</h2>
<p>This chapter describes how to use the <a class="reference external" href="/native-client/pepper_stable/cpp/classpp_1_1_u_r_l_loader">URLLoader API</a> to load resources
such as images and sound files from a server into your application.</p>
<p>The example discussed in this chapter is included in the SDK in the directory
<code>examples/api/url_loader</code>.</p>
</section><section id="reference-information">
<h2 id="reference-information">Reference information</h2>
<p>For reference information related to loading data from URLs, see the
following documentation:</p>
@@ -39,7 +37,6 @@ following documentation:</p>
<li><a class="reference external" href="/native-client/pepper_stable/cpp/url__response__info_8h">url_response_info.h</a> - Contains
<code>URLResponse</code> class for examaning URL responses</li>
</ul>
</section><section id="background">
<h2 id="background">Background</h2>
<p>When a user launches your Native Client web application, Chrome downloads and
caches your application&#8217;s HTML file, manifest file (.nmf), and Native Client
@@ -51,7 +48,6 @@ application.</p>
assets. To avoid being at the whim of the Chrome cache, however, you may want
to use the <a class="reference external" href="/native-client/pepper_stable/cpp/classpp_1_1_file_i_o">Pepper FileIO API</a> to write those assets
to a persistent, sandboxed location on the user&#8217;s file system.</p>
</section><section id="the-url-loader-example">
<h2 id="the-url-loader-example">The <code>url_loader</code> example</h2>
<p>The SDK includes an example called <code>url_loader</code> demonstrating downloading
files from a server. This example has these primary files:</p>
@@ -70,7 +66,6 @@ bulk of the work is done).</li>
</ul>
<p>The remainder of this document covers the code in the <code>url_loader.cc</code> and
<code>url_loader_handler.cc</code> files.</p>
<section id="url-loading-overview">
<h3 id="url-loading-overview">URL loading overview</h3>
<p>Like many Pepper APIs, the <code>URLLoader</code> API includes a set of methods that
execute asynchronously and that invoke callback functions in your Native Client
@@ -96,9 +91,7 @@ files and fast connections).</li>
</ol>
<p>The remainder of this document demonstrates how the previous steps are
implemented in the <code>url_loader</code> example.</p>
</section></section><section id="url-loader-deep-dive">
<h2 id="url-loader-deep-dive"><code>url_loader</code> deep dive</h2>
<section id="setting-up-the-request">
<h3 id="setting-up-the-request">Setting up the request</h3>
<p><code>HandleMessage</code> in <code>url_loader.cc</code> creates a <code>URLLoaderHandler</code> instance
and passes it the URL of the asset to be retrieved. Then <code>HandleMessage</code>
@@ -146,7 +139,6 @@ URLLoaderHandler::URLLoaderHandler(pp::Instance* instance,
url_request_.SetRecordDownloadProgress(true);
}
</pre>
</section><section id="downloading-the-data">
<h3 id="downloading-the-data">Downloading the data</h3>
<p><code>Start</code> in <code>url_loader_handler.cc</code> creates a callback (<code>cc</code>) using a
<code>CompletionCallbackFactory</code>. The callback is passed to <code>Open</code> to be called
@@ -219,12 +211,11 @@ in <code>PP_OK</code> or 0), all the bytes have been read for what has been
downloaded, but more is to be downloaded (<code>PP_OK_COMPLETIONPENDING</code> or -1),
or there is an error (less than -1). <code>OnRead</code> is called in the event of an
error or <code>PP_OK</code>.</p>
</section><section id="displaying-a-result">
<h3 id="displaying-a-result">Displaying a result</h3>
<p>OnRead calls <code>ReportResultAndDie</code> when either an error or <code>PP_OK</code> is
returned to indicate streaming of file is complete. <code>ReportResultAndDie</code> then
calls <code>ReportResult,</code> which calls <code>PostMessage</code> to send the result back to
the HTML page.</p>
</section></section></section>
</section>
{{/partials.standard_nacl_article}}

10
native_client_sdk/doc_generated/devguide/coding/view-focus-input-events.html

@@ -34,7 +34,6 @@ ppapi_simple library that can be used to to implement most of the
boiler plate. The <code>pi_generator</code> example in
<code>/examples/demo/pi_generator</code> uses ppapi_simple to manage view
change events and 2D graphics.</p>
<section id="overview">
<h2 id="overview">Overview</h2>
<p>When a user interacts with the web page using a keyboard, mouse or some other
input device, the browser generates input events. In a traditional web
@@ -156,9 +155,7 @@ branches accordingly.</td>
</table>
<p>These interfaces are found in the <a class="reference external" href="/native-client/pepper_stable/cpp/classpp_1_1_instance">pp::Instance class</a>. The sections below
provide examples of how to handle these events.</p>
</section><section id="handling-browser-events">
<h2 id="handling-browser-events">Handling browser events</h2>
<section id="didchangeview">
<h3 id="didchangeview">DidChangeView()</h3>
<p>In the <code>mouse_lock</code> example, <code>DidChangeView()</code> checks the previous size
of instance&#8217;s rectangle versus the new size. It also compares
@@ -195,7 +192,6 @@ void MouseLockInstance::DidChangeView(const pp::View&amp; view) {
<li><a class="reference external" href="/native-client/pepper_stable/cpp/classpp_1_1_image_data">pp::ImageData class</a></li>
<li><a class="reference external" href="/native-client/pepper_stable/cpp/classpp_1_1_graphics2_d">pp::Graphics2D class</a></li>
</ul>
</section><section id="didchangefocus">
<h3 id="didchangefocus">DidChangeFocus()</h3>
<p><code>DidChangeFocus()</code> is called when you click inside or outside of a
module&#8217;s instance in the web page. When the instance goes out
@@ -208,13 +204,11 @@ void DidChangeFocus(bool focus) {
// the instance.
}
</pre>
</section></section><section id="handling-input-events">
<h2 id="handling-input-events">Handling input events</h2>
<p>Input events are events that occur when the user interacts with a
module instance using the mouse, keyboard, or other input device
(e.g., touch screen). This section describes how the <code>input_events</code>
example handles input events.</p>
<section id="registering-a-module-to-accept-input-events">
<h3 id="registering-a-module-to-accept-input-events">Registering a module to accept input events</h3>
<p>Before your module can handle these events, you must register your
module to accept input events using <code>RequestInputEvents()</code> for mouse
@@ -238,7 +232,6 @@ combination of flags that identify the class of events that the instance is
requesting to receive. Input event classes are defined in the
<a class="reference external" href="/native-client/pepper_stable/c/group___enums.html#gafe68e3c1031daa4a6496845ff47649cd">PP_InputEvent_Class</a>
enumeration in <a class="reference external" href="/native-client/pepper_stable/c/ppb__input__event_8h">ppb_input_event.h</a>.</p>
</section><section id="determining-and-branching-on-event-types">
<h3 id="determining-and-branching-on-event-types">Determining and branching on event types</h3>
<p>In a typical implementation, the <code>HandleInputEvent()</code> function determines the
type of each event using the <code>GetType()</code> function found in the <code>InputEvent</code>
@@ -330,7 +323,6 @@ following documentation:</p>
<li><a class="reference external" href="/native-client/pepper_stable/c/classpp_1_1_wheel_input_event">pp::WheelInputEvent class</a></li>
<li><a class="reference external" href="/native-client/pepper_stable/c/classpp_1_1_keyboard_input_event">pp::KeyboardInputEvent class</a></li>
</ul>
</section><section id="threading-and-blocking">
<h3 id="threading-and-blocking">Threading and blocking</h3>
<p><code>HandleInputEvent()</code> in this example runs on the main module thread.
However, the bulk of the work happens on a separate worker thread (see
@@ -338,6 +330,6 @@ However, the bulk of the work happens on a separate worker thread (see
the <code>event_queue_</code> and the worker thread takes events from the
<code>event_queue_</code>. This processing happens independently of the main
thread, so as not to slow down the browser.</p>
</section></section></section>
</section>
{{/partials.standard_nacl_api}}