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.
- 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
- 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.
- 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.
- The stream will never be seeked.
- See also:
- 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
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.
- 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.