X3D libraries
The libraries to work with X3D dataset
x3dxml::XMLReader

x3dxml::XMLReader Class Reference

An implementation of x3dio::Reader used to read a stream and convert it to a tree of x3d nodes. More...

#include <xml.h>

Inheritance diagram for x3dxml::XMLReader:

Inheritance graph
[legend]
Collaboration diagram for x3dxml::XMLReader:

Collaboration graph
[legend]
List of all members.

Public Member Functions

virtual x3d::SFNodePtr Load (x3dio::Stream *stream, x3dio::ErrorCallback *callback=0)
 Load stream into a tree of nodes from an XML file.
 XMLReader ()
 Initialize the XML reader.
virtual ~XMLReader ()
 Destroy the XML reader.

Detailed Description

An implementation of x3dio::Reader used to read a stream and convert it to a tree of x3d nodes.

The XML reader is a very optimized XML parser which takes a wellformed X3D tree and loads it in an X3D tree of nodes. The input file is expected to be UTF-8.

See the Load() function for more information about the input file.

You can instantiate the class on your stack or create an object with the new operator.

 x3dio::FileStream stream;
 stream.Open("my_shape.x3d");
 x3dxml::XMLReader xml_out;
 // note: ignore errors
 x3d::SFNodePtr root = xml_out.Load(stream);
 ... // do something with root

See also:
XMLReader

Constructor & Destructor Documentation

x3dxml::XMLReader::XMLReader (   ) 
 

Initialize the XML reader.

The constructor will make sure that the reader is ready to be used.

x3dxml::XMLReader::~XMLReader (   )  [virtual]
 

Destroy the XML reader.

The destructor deletes all the objects used internally.

Member Function Documentation

x3d::SFNodePtr x3dxml::XMLReader::Load (  x3dio::Stream *  stream,
x3dio::ErrorCallback *  callback = 0
)  [virtual]
 

Load stream into a tree of nodes from an XML file.

This function reads the input stream and create the corresponding X3D nodes. The input is expected to be a valid X3D XML file in text format.

This means:

  • the nodes are properly arranged (proper parent/child relations)
  • the file is in UTF-8
  • the file starts with a valid <?xml ... ?> mark
  • the first tag is an <X3D> tag
  • if extensions are used in the file, these are defined in the libx3d system before this function is called.
  • if there is a DOCTYPE specification, it needs to name X3D
  • if the X3D tag specifies the version, it must be 3.0 or better
Remarks:
This function implements its own XML parser (and at time of writing, it is less than 1000 lines including this documentation!). This is really fast since it does not need to create an XML tree, only an optimized libx3d tree. We gain time especially because we will not have all the strings allocated multiple times in memory. As soon as the parser gets the name of a tag, that name is converted to a field_t identifier. This means the buffer used to read the tag name can now be used to read the name of the attributes of that tag (if any), read the next tag, etc.
Warning:
X3D version 3.1 is a cannonalized version in binary format with the tags saved in a very specific order. libx3d does not support that format yet.
Note:
The stream will never be seeked.
See also:
x3dxml::XMLWriter
Warning:
The XML checking is pretty loosy. For instance, the closing tags are not matched against the corresponding opening tag. As long as the input files are wellformed, it should not matter. Adding more code to check for such problems would just slow down the parser. If you have a file that you are not sure is properly formatted, I suggest you test it with xmllint to see whether it is a valid xml. xmllint is capable to test the file against the proper DTD definitions (i.e. checks the order in which children nodes are defined, whether tags are properly closed, whether attributes are known. etc.)

Save the specified (root) node in the output stream.

This function is expected to be implemented by different libraries supporting different file formats (such as XML, VRML, OBJ, RAW, etc.)

The node is always expected to be a root node (i.e. an X3D node). If the node is not of the right type, the function should fail (thought some implementations may be capable of saving just a shape or some other X3D object).

The user can specify an error callback object. In this case, any error generated in the writer will be reported to the caller. Please, see the reference about the x3dio::ErrorCallback for more information on how messages are forwarded.

Note:
The writer can only write to the stream. Some writer's may need support for the x3dio::Stream::Seek() instruction. Please, see the reference of each writer for more information about that writer.

Implements x3dio::Reader.

The documentation for this class was generated from the following files: