<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>OpenVRML: 3 libopenvrml - the run-time library</title>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<link rel="icon" href="../vrml-16">
<link rel="start" href="http://openvrml.org/index" title="OpenVRML Home">
<link rel="prev" href="http://openvrml.org/discussion" title="Discussion">
<link rel="contents" href="index" title="Documentation Main Page">
<link rel="index" href="functions" title="OpenVRML Compound Members">
<link rel="appendix" href="conformance" title="Conformance Test Results">
<style type="text/css">
@import url("tabs.css");
@import url("http://openvrml.org/openvrml.css");
table {
width: 100%;
}
h2 {
border-bottom-style: solid;
border-bottom-width: 1px;
}
/*
* Doxygen as of 1.5.4-20071217 uses the class "navpath" instead of "nav".
* For now, we'll do both.
*/
div.nav,
div.navpath {
background-color: transparent;
text-align: left;
margin-top: 1em;
margin-bottom: 1em;
border-color: black;
border-left: none;
border-right: none;
padding-top: 0.5em;
padding-bottom: 0.5em;
}
div.nav :link, div.nav :visited,
div.navpath :link, div.navpath :visited {
border-width: 1px;
border-style: solid;
border-color: silver;
padding: 2px;
}
div.nav :link:hover, div.nav :visited:hover,
div.navpath :link:hover, div.navpath :visited:hover {
border-style: outset;
border-color: gray;
}
div.nav :active,
div.navpath :active {
border-style: inset;
border-color: gray;
}
.body td {
background-color: transparent;
}
.el {
text-decoration: inherit;
font-weight: inherit
}
.elRef {
font-weight: inherit
}
.code:link, .code:visited {
text-decoration: inherit;
font-weight: inherit;
color: inherit;
}
.codeRef:link {
font-weight: normal;
color: inherit;
}
:visited {
color: silver;
}
:link:hover {
color: inherit;
text-decoration: inherit;
background-color: transparent;
}
h1 {
line-height: 1.2em;
}
td.memItemLeft, td.memItemRight,
td.memTemplParams, td.memTemplItemLeft, td.memTemplItemRight,
.memtemplate, .memname td {
font-family: Consolas, "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Lucida Console", LucidaTypewriter, monospace;
}
td.memItemLeft, td.memItemRight, td.mdescLeft, td.mdescRight {
background-color: rgb(95%, 95%, 95%);
border-color: rgb(65%, 65%, 65%);
border-width: 1px;
font-size: smaller;
}
.memItemLeft {
margin-top: 0.5em;
border-top-style: solid;
}
.mdescLeft {
border-bottom-style: solid;
}
.memItemRight {
border-top-style: solid;
margin-top: 0.5em;
}
.mdescRight {
border-bottom-style: solid;
}
.mdescRight {
font-style: italic;
}
.mdTable {
background-color: rgb(95%, 95%, 95%);
}
.memproto td code {
font-family: inherit;
font-style: italic;
}
td.pass {
background-color: rgb(50%, 100%, 50%);
}
td.fail {
background-color: rgb(100%, 50%, 50%);
}
td.invalid {
background-color: rgb(75%, 75%, 75%);
}
.memitem {
padding: 0;
}
.memitem table {
width: auto;
}
.memproto, .memdoc {
border-width: 1px;
border-color: rgb(65%, 65%, 65%);
}
.memproto {
background-color: rgb(90%, 90%, 90%);
font-weight: inherit;
font-size: smaller;
border-top-style: solid;
border-left-style: solid;
border-right-style: solid;
-webkit-border-top-left-radius: 0.6em;
-webkit-border-top-right-radius: 0.6em;
-moz-border-radius-topleft: 0.6em;
-moz-border-radius-topright: 0.6em;
}
.memdoc {
background-color: rgb(95%, 95%, 95%);
padding: 2px 5px;
border-style: solid;
-webkit-border-bottom-left-radius: 0.6em;
-webkit-border-bottom-right-radius: 0.6em;
-moz-border-radius-bottomleft: 0.6em;
-moz-border-radius-bottomright: 0.6em;
}
.memname {
font-weight: inherit;
}
div.tabs {
background-image: url("tab_b-openvrml.png");
}
div.tabs span {
background-image: url("tab_l-openvrml.png");
}
div.tabs a {
background-image: url("tab_r-openvrml.png");
border-bottom: 1px solid #a5a5a5;
}
div.tabs a:link, div.tabs a:visited, div.tabs a:active, div.tabs a:hover {
color: black;
}
table {
border-collapse: collapse;
border-spacing: 0;
}
.note {
border: 1px solid rgb(65%, 65%, 65%);
background-color: rgb(95%, 95%, 95%);
margin-left: 10%;
margin-right: 10%;
}
</style>
</head>
<body>
<table class="sitenav">
<tr>
<th><a href="http://openvrml.org/index" title="Home">Home</a></th>
<th><a href="http://openvrml.org/download" title="Download">Download</a></th>
<th><a href="http://openvrml.org/screenshots/index" title="Screen shots">Screen shots</a></th>
<th><a href="http://openvrml.org/discussion" title="Mailing lists and IRC">Discussion</a></th>
<th>Documentation</th>
</tr>
</table>
<div class="body">
<!-- Generated by Doxygen 1.5.8 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
</ul>
</div>
<div class="navpath"><a class="el" href="index.html">OpenVRML User's Guide</a>
</div>
</div>
<div class="contents">
<h1><a class="anchor" name="libopenvrml">3 libopenvrml - the run-time library </a></h1><h2><a class="anchor" name="resource_fetching">
3.1 Fetching network resources</a></h2>
<h3><a class="anchor" name="resource_fetching_rationale">
3.1.1 Rationale</a></h3>
A VRML/X3D runtime must, of course, be able to fetch network resources using URIs. However, there is no standard mechanism in C++ for network communication. Various libraries are available to fill this void; but if OpenVRML were to depend on one of them it could make OpenVRML more difficult to integrate into applications that use some different network layer.<p>
In order to integrate into systems using arbitrary mechanisms for network I/O, OpenVRML requires the user to supply a resource fetching facility. As such, the URI schemes (and corresponding resolution and transfer protocols) supported in worlds loaded into OpenVRML are a function of the user-supplied resource fetching mechanism.<p>
The resource fetching mechanism can be as full-featured or as spartan as the user application requires. A minimal facility might only handle <code>file</code> URLs. But in general it is desirable to support at least the schemes supported by modern Web browsers (significantly, <code>ftp</code> and <code>http</code>).<h3><a class="anchor" name="resource_istream">
3.1.2 resource_istream and resource_fetcher</a></h3>
OpenVRML accomplishes this extensibility by extending the C++ IOStreams framework. <code><a class="el" href="classopenvrml_1_1resource__istream.html" title="An abstract input stream for network resources.">openvrml::resource_istream</a></code> inherits <code>std::istream</code> and adds a few member functions particular to network resource fetching:<p>
<div class="fragment"><pre class="fragment"> <span class="keyword">const</span> std::string url() <span class="keyword">const</span> throw (std::bad_alloc);
const std::<span class="keywordtype">string</span> type() const throw (std::bad_alloc);
<span class="keywordtype">bool</span> data_available() const throw ();
</pre></div><p>
<code>resource_istream</code> is an abstract class. It is an interface through which OpenVRML can access user code. You use <code>resource_istream</code> by inheriting it and providing implementations for its pure virtual functions.<p>
OpenVRML constructs <code>resource_istream</code> instances through the <code>resource_fetcher</code> interface. <code>resource_fetcher</code> is an <a href="http://en.wikipedia.org/wiki/Abstract_factory_pattern">abstract factory</a> that also must be implemented by user code.<p>
<code>resource_fetcher</code> has a single pure virtual function that must be implemented:<p>
<div class="fragment"><pre class="fragment"> <span class="keyword">virtual</span> std::auto_ptr<resource_istream> do_get_resource(<span class="keyword">const</span> std::string & uri) = 0;
</pre></div><p>
<code>do_get_resource</code> is, essentially, a construction function for concrete <code>resource_istreams</code>. The API documentation for <code><a class="el" href="classopenvrml_1_1resource__fetcher.html#3a79534184e9de4e6405a52c19336ca6" title="Fetch a network resource.">openvrml::resource_fetcher::do_get_resource</a></code> provides details on the requirements for this function's implementation. Briefly, your implementation will return a <code>std::auto_ptr</code> to an instance of your class that implements <code><a class="el" href="classopenvrml_1_1resource__istream.html" title="An abstract input stream for network resources.">openvrml::resource_istream</a></code>.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd>Most “factory functions” (i.e., functions that return an instance of an object allocated with <code>new</code>) in OpenVRML return an <code>auto_ptr</code>. <code>std::auto_ptr</code> is used for ownership transfer; its use for a return value signals that the caller is taking ownership of the resource.</dd></dl>
<h3><a class="anchor" name="introducing_browser">
3.1.3 Introducing browser</a></h3>
The centerpiece of OpenVRML is <code><a class="el" href="classopenvrml_1_1browser.html" title="Encapsulates a VRML browser.">openvrml::browser</a></code>. This class provides the interface for loading VRML/X3D worlds. Most management of the runtime will be handled through its member functions. <code>browser</code> is instantiated with a concrete subclass of <code>resource_fetcher</code> along with <code>std::ostream</code> instances where normal console output and error console output should be sent.<h3><a class="anchor" name="resource_istream_impl_considerations">
3.1.4 resource_istream implementation considerations</a></h3>
OpenVRML supports a notion of data streaming. In general, network resources are read asynchronously with respect to the rendering thread. User code that does not support data streaming (as in the example using <code>std::filebuf</code> in the documentation for <code><a class="el" href="classopenvrml_1_1resource__fetcher.html#3a79534184e9de4e6405a52c19336ca6" title="Fetch a network resource.">openvrml::resource_fetcher::do_get_resource</a></code>) can remain largely oblivious to synchronization issues. However, user code that supports data streaming must be mindful of the fact that OpenVRML uses separate threads to read the data streams. Care must be taken not to write to a buffer at the same time OpenVRML's stream reading thread is reading the buffer.<p>
The IOStreams framework is typically extended by inheriting <code>std::streambuf</code> to implement new sources and sinks for data. (Full treatment of this topic is beyond the scope of this document; see <a href="http://www.josuttis.com/libbook/"><em>The C++ Standard Library</em> by Nicolai M. Josuttis</a> and <a href="http://www.angelikalanger.com/iostreams.html"><em>Standard C++ IOStreams and Locales</em> by Angelika Langer and Klaus Kreft</a>.) However, <code>std::streambuf</code>'s interface is not thread-safe. Since OpenVRML's stream-reading thread can be expected to be using the <code>streambuf</code> interface (by way of the <code>std::istream</code> member functions inherited by <code><a class="el" href="classopenvrml_1_1resource__istream.html" title="An abstract input stream for network resources.">openvrml::resource_istream</a></code>), it is only safe for user code to use the <code>streambuf</code> interface in that same thread; i.e., in code called by OpenVRML.<p>
If user code needs to feed data into a buffer in a separate thread, that buffer should not be the one managed by the <code>streambuf</code> interface (i.e., the buffer to which <code>eback</code>, <code>gptr</code>, and <code>egptr</code> point). In general it is appropriate to use a secondary buffer, protected with thread synchronization primitives, for writing incoming data. Data can then be moved from this buffer to the <code>streambuf</code>'s buffer in the implementation of <code>std::streambuf::underflow</code>. </div>
</div>
<address class="footer"><span class="images"><a href="http://web3d.org/x3d/"><img src="x3d-white-on-black.png" width="43" height="32" border="0" alt="X3D"></a><a href="http://opengl.org"><img src="OGL_sm_wht.png" width="68" height="32" border="0" alt="OpenGL"></a><a href="http://sourceforge.net/projects/openvrml"><img src="http://sourceforge.net/sflogo.php?group_id=7151&type=11" width="120" height="30" border="0" alt="SourceForge.net"></a></span><a href="https://sourceforge.net/apps/trac/openvrml/newticket">Report error</a><br>Generated Thu Aug 13 02:49:12 2009 by Doxygen 1.5.8</address>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
<script type="text/javascript">_uacct = "UA-446379-2"; urchinTracker();</script>
<!-- Piwik -->
<script type="text/javascript">
var pkBaseURL = (("https:" == document.location.protocol) ? "https://sourceforge.net/apps/piwik/openvrml/" : "http://sourceforge.net/apps/piwik/openvrml/");
document.write(unescape("%3Cscript src='" + pkBaseURL + "piwik.js' type='text/javascript'%3E%3C/script%3E"));
</script><script type="text/javascript">
piwik_action_name = '';
piwik_idsite = 1;
piwik_url = pkBaseURL + "piwik.php";
piwik_log(piwik_action_name, piwik_idsite, piwik_url);
</script>
<object><noscript><p><img src="http://sourceforge.net/apps/piwik/openvrml/piwik.php?idsite=1" alt="piwik"/></p></noscript></object>
<!-- End Piwik Tag -->
</body>
</html>
