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.
The resource fetching mechanism can be as full-featured or as spartan as the user application requires. A minimal facility might only handle
file URLs. But in general it is desirable to support at least the schemes supported by modern Web browsers (significantly,
std::istreamand adds a few member functions particular to network resource fetching:
const std::string url() const throw (std::bad_alloc); const std::string type() const throw (std::bad_alloc); bool data_available() const throw ();
resource_istream is an abstract class. It is an interface through which OpenVRML can access user code. You use
resource_istream by inheriting it and providing implementations for its pure virtual functions.
resource_istream instances through the
resource_fetcher is an abstract factory that also must be implemented by user code.
resource_fetcher has a single pure virtual function that must be implemented:
virtual std::auto_ptr<resource_istream> do_get_resource(const std::string & uri) = 0;
do_get_resource is, essentially, a construction function for concrete
resource_istreams. The API documentation for
openvrml::resource_fetcher::do_get_resource provides details on the requirements for this function's implementation. Briefly, your implementation will return a
std::auto_ptr to an instance of your class that implements
new) in OpenVRML return an
std::auto_ptris used for ownership transfer; its use for a return value signals that the caller is taking ownership of the resource.
openvrml::browser. This class provides the interface for loading VRML/X3D worlds. Most management of the runtime will be handled through its member functions.
browseris instantiated with a concrete subclass of
std::ostreaminstances where normal console output and error console output should be sent.
std::filebufin the documentation for
openvrml::resource_fetcher::do_get_resource) 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.
The IOStreams framework is typically extended by inheriting
std::streambuf to implement new sources and sinks for data. (Full treatment of this topic is beyond the scope of this document; see The C++ Standard Library by Nicolai M. Josuttis and Standard C++ IOStreams and Locales by Angelika Langer and Klaus Kreft.) However,
std::streambuf's interface is not thread-safe. Since OpenVRML's stream-reading thread can be expected to be using the
streambuf interface (by way of the
std::istream member functions inherited by
openvrml::resource_istream), it is only safe for user code to use the
streambuf interface in that same thread; i.e., in code called by OpenVRML.
If user code needs to feed data into a buffer in a separate thread, that buffer should not be the one managed by the
streambuf interface (i.e., the buffer to which
egptr 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
streambuf's buffer in the implementation of