-
Notifications
You must be signed in to change notification settings - Fork 9
/
README
435 lines (346 loc) · 18.3 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
OpenVRML library version 0.18.99
Copyright 1998, 1999, 2000 Chris Morley <cmorley@vermontel.net>
Copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
2011, 2012 Braden McDaniel <braden@endoframe.com>
Portions Copyright SGI and others
Available from <http://openvrml.org>
See the "NEWS" file for a list of changes in this release.
About
=====
OpenVRML is a portable toolkit including a C++ library for reading
and displaying VRML and X3D files, an OpenGL renderer, and a Mozilla
Web browser plug-in for viewing VRML and X3D content on the Internet.
License terms
=============
The OpenVRML libraries comprising the VRML/X3D runtime ("libopenvrml")
and the OpenGL renderer ("libopenvrml-gl") are available under the terms
of the GNU Lesser General Public License (LGPL), version 3. These
libraries incorporate some code that is available under "LGPL-
compatible" licenses, which effectively means that the OpenVRML
libraries are Free Software which may be used collectively according to
the terms of the LGPL. The full text of the LGPL can be found in the
file "COPYING.LESSER". Code used in these libraries under other terms
(and available for reuse under the same terms) is as follows:
* OpenVRML's OpenGL renderer includes code from Silicon Graphics, Inc.:
(c) Copyright 1993, 1994, Silicon Graphics, Inc.
ALL RIGHTS RESERVED
Permission to use, copy, modify, and distribute this software for
any purpose and without fee is hereby granted, provided that the
above copyright notice appear in all copies and that both the
copyright notice and this permission notice appear in supporting
documentation, and that the name of Silicon Graphics, Inc. not be
used in advertising or publicity pertaining to distribution of the
software without specific, written prior permission.
THE MATERIAL EMBODIED ON THIS SOFTWARE IS PROVIDED TO YOU "AS-IS"
AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE,
INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL SILICON
GRAPHICS, INC. BE LIABLE TO YOU OR ANYONE ELSE FOR ANY DIRECT,
SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY
KIND, OR ANY DAMAGES WHATSOEVER, INCLUDING WITHOUT LIMITATION,
LOSS OF PROFIT, LOSS OF USE, SAVINGS OR REVENUE, OR THE CLAIMS OF
THIRD PARTIES, WHETHER OR NOT SILICON GRAPHICS, INC. HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH LOSS, HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE
POSSESSION, USE OR PERFORMANCE OF THIS SOFTWARE.
US Government Users Restricted Rights
Use, duplication, or disclosure by the Government is subject to
restrictions set forth in FAR 52.227.19(c)(2) or subparagraph
(c)(1)(ii) of the Rights in Technical Data and Computer Software
clause at DFARS 252.227-7013 and/or in similar or successor
clauses in the FAR or the DOD or NASA FAR Supplement.
Unpublished-- rights reserved under the copyright laws of the
United States. Contractor/manufacturer is Silicon Graphics,
Inc., 2011 N. Shoreline Blvd., Mountain View, CA 94039-7311.
OpenGL(TM) is a trademark of Silicon Graphics, Inc.
The XEmbed control, OpenVRML Player, and the Mozilla plug-in as
well as the included example programs are available under the terms of
the GNU General Public License (GPL), version 3. The full text of the
GPL can be found in the file "COPYING".
Package directory layout
========================
/data
/component : XML component definitions.
/doc
/manual : API documentation.
/examples : Example programs.
/ide-projects
/Windows
/VisualC9_0 : Microsoft Visual C++ 9.0 project files.
/m4 : m4 macros used by the GNU build system.
/models : Sample VRML models.
/src
/libopenvrml : Runtime library sources.
/libopenvrml-gl : OpenGL renderer library sources.
/mozilla-plugin : Mozilla plug-in sources.
/node
/vrml97 : VRML97 node implementation sources.
/x3d-cad-geometry : X3D CAD Geometry component node
implementation sources.
/x3d-core : X3D Core component node implementation
sources.
/x3d-dis : X3D DIS component node implementation
sources.
/x3d-environmental-effects : X3D Environmental Effects component node
implementation sources.
/x3d-event-utilities : X3D Event Utilities component node
implementation sources.
/x3d-geometry2d : X3D Geometry2D component node
implementation sources.
/x3d-geospatial : X3D Geospatial component node
implementation sources.
/x3d-grouping : X3D Grouping component node
implementation sources.
/x3d-h-anim : X3D H-Anim component node implementation
sources.
/x3d-interpolation : X3D Interpolation component node
implementation sources.
/x3d-key-device-sensor : X3D Key Device Sensor component node
implementation sources.
/x3d-networking : X3D Networking component node
implementation sources.
/x3d-nurbs : X3D NURBS component node implementation
sources.
/x3d-rendering : X3D Rendering component node
implementation sources.
/x3d-shape : X3D Shape component node implementation
sources.
/x3d-texturing : X3D Texturing component node
implementation sources.
/openvrml-xembed : XEmbed control application sources.
/openvrml-player : OpenVRML Player application sources.
/script : Scripting engine module sources.
/java : Script node Java API sources.
/tests : Test programs.
Prerequisites
=============
At a minimum, OpenVRML requires these libraries to build:
Boost (at least 1.44) <http://boost.org>
libltdl (non-Windows only) <http://www.gnu.org/software/libtool/>
libxml (non-Windows only) <http://xmlsoft.org>
These libraries are packaged for many systems; so you should
consult your operating system vendor if any of them is not already
installed on your system. Otherwise, you can obtain them at the above
URIs.
Note that Boost binaries built from the boost.org distribution, as
well as some other distributions, apply a suffix to the library
name that depends on the particular build configuration. When
building OpenVRML with such binaries it may be necessary to set the
variable BOOST_LIB_SUFFIX to match the suffix applied to the Boost
binaries; refer to the output of "configure --help".
libltdl and libxml are not required on Microsoft Windows platforms.
On Windows, OpenVRML uses the Win32 API for module loading and the
XmlLite library for XML parsing. XmlLite is included with recent
versions of the Microsoft Windows SDK.
Building OpenVRML is fairly demanding of system resources;
especially, it seems, with modern versions of the GNU C++ compiler. It
is recommended that 32-bit build hosts have at least 1 GB of system
memory; the recommended minimum for 64-bit build hosts is 2 GB.
Optional dependencies
=====================
OpenVRML has several optional dependencies. If your system is
missing any of these dependencies, first check to see if they are
provided by your operating system vendor. If not, consult the URIs
below.
libpng <http://www.libpng.org/pub/png/libpng.html>
libjpeg <http://www.ijg.org>
FreeType <http://freetype.org>
Fontconfig <http://fontconfig.org>
XULRunner <https://developer.mozilla.org/En/XULRunner>
Java Development Kit <http://java.sun.com/j2se/>
OpenGL/Mesa <http://mesa3d.org>
GTK+ <http://gtk.org>
GtkGLExt <http://gtkglext.sourceforge.net>
libcurl <http://curl.haxx.se/libcurl/>
D-Bus <http://www.freedesktop.org/wiki/Software/dbus>
GNOME <http://gnome.org>
SDL <http://libsdl.org>
Doxygen <http://doxygen.org>
OpenVRML can be built with reduced functionality which can avoid
these dependencies. See the following section, "'configure' options",
for details.
"configure" options
===================
OpenVRML's build configuration script accepts a number of arguments
that modify what features are built and/or what packages OpenVRML
depends on.
--enable-exception-specs[=yes,no,nothrow]
Modulate use of C++ exception specifications. By default,
OpenVRML uses exception specifications wherever the set of
exceptions thrown from a function can be constrained. This can
aid in debugging; but in general it is likely to degrade
performance. Exception specifications can be disabled altogether
(using an argument of "no" or the option
"--disable-exception-specs"); or, only empty (i.e., nonthrowing)
exception specifications can be enabled (using an argument of
"nothrow"). Some compilers may be able to use the nonthrowing
exception specification as an optimization hint. Note that
changing what exception specifications are applied changes the
library ABI.
--enable-gecko-rpath
Enable use of the Gecko runtime library directory -rpath flag. On
many systems, the directory where libmozjs.so and other Gecko
runtime libraries reside is not a path known to the dynamic linker.
In such cases, applying an -rpath to executables is frequently a
desirable alternative to setting LD_RUN_PATH before running them.
--disable-png-textures
Disable support for rendering PNG images as textures. OpenVRML
uses libpng to read PNG images.
--disable-jpeg-textures
Disable support for rendering JPEG images as textures. OpenVRML
uses libjpeg to read JPEG images.
--disable-render-text-node
Disable support for rendering Text nodes. The node is still
parsed, and events to and from it are processed; but no text is
rendered. By default OpenVRML uses Fontconfig for font discovery
and FreeType to get font data.
--disable-script-node-javascript
Disable support for JavaScript in the Script node. By default,
OpenVRML uses the Mozilla JavaScript library to execute JavaScript.
--disable-script-node-java
Disable support for Java in the Script node. "configure" searches
for a Java Native Interface (JNI) implementation, which may be
provided either by a Java Development Kit or the GNU Compiler for
Java (gcj). If using a Java Development Kit, you will probably
need to supply the include and library directories using CPPFLAGS
and LDFLAGS, respectively. See the file INSTALL for general
information on using these variables.
--disable-gl-renderer
Do not build the GL renderer. OpenVRML's GL renderer depends on
OpenGL/Mesa.
--disable-xembed
Do not build the XEmbed control. This is an out-of-process
component that provides a VRML/X3D browser that can be used in an
XEmbed container. This depends on GTK+. It also requires that
the GL renderer be built.
--disable-player
Do not build openvrml-player. This is a GNOME application that
hosts the XEmbed control. It depends on GNOME (libgnomeui) and
libcurl.
--disable-mozilla-plugin
Do not build the Mozilla plug-in. The Mozilla plug-in depends on
GTK+ and, of course, a Mozilla-based browser. It also requires
that the XEmbed control be built.
--disable-examples
Do not build the example programs. The example programs depend on
SDL.
--with-x
Passing the argument "--without-x" to "configure" will allow
OpenVRML to be built without depending on the X Windowing System.
This option is really only useful when building OpenVRML on
platforms where X is available alongside another windowing system
(e.g., Cygwin or Mac OS X with X installed).
--with-libjs
Use the stand-alone SpiderMonkey distribution. By default,
"configure" looks for SpiderMonkey as it is distributed with a
Mozilla Gecko-based Web browser (i.e., libmozjs). Passing the
argument "--with-libjs" causes "configure" to look instead for the
stand-alone distribution of SpiderMonkey (i.e., libjs).
Significant preprocessor symbols
================================
Certain code in OpenVRML is compiled conditionally depending on what
symbols have been defined for the preprocessor. The "configure" script
will add the appropriate compiler and preprocessor flags for you; in
general you should use the options to "configure" documented in the
previous section rather than define these symbols in CPPFLAGS. These
symbols are documented here primarily for the benefit of persons trying
to compile OpenVRML without the GNU build tools.
OPENVRML_ENABLE_PNG_TEXTURES
Include support for rendering PNG images as textures. Requires
libpng.
OPENVRML_ENABLE_JPEG_TEXTURES
Include support for rendering JPEG images as textures. Requires
libjpeg.
OPENVRML_ENABLE_RENDER_TEXT_NODE
Include support for rendering text using the Text node. Requires
fontconfig and FreeType.
OPENVRML_JNI_CONST
Define to "const" if "const" should be used in JNI function
signatures; define to empty otherwise.
Installation
============
Refer to the file "INSTALL" for detailed installation instructions.
Usage
=====
To write programs that use the OpenVRML libraries, refer to the API
documentation in the "doc/manual" subdirectory of the distribution and
the example programs in the "examples" subdirectory.
libopenvrml loads data files and plug-ins from known locations once
it is installed. If they are defined, libopenvrml will prefer the
locations specified by these environment variables:
OPENVRML_DATADIR
Directory where libopenvrml looks for architecture-independent
data.
OPENVRML_NODE_PATH
A search path where libopenvrml looks for node implementations.
OPENVRML_SCRIPT_PATH
A search path where libopenvrml looks for scripting engine
implementations.
The most common use case for setting these environment variables is
running sdl-viewer or openvrml-xembed from the build directories. For
example, if running a Bash shell and building in a subdirectory
"build" where the current directory is the root of the OpenVRML
distribution:
$ OPENVRML_DATADIR=$(pwd)/data \
OPENVRML_NODE_PATH=$(pwd)/build/src/node \
OPENVRML_SCRIPT_PATH=$(pwd)/build/src/script \
./build/examples/sdl-viewer models/rotation_toy.wrl
openvrml-xembed is installed as a D-Bus service, meaning that it
can be activated on-demand by applications that need it (like
openvrml-player and the Mozilla plug-in). In order for this to work,
OpenVRML must be installed to the same prefix as the system's D-Bus
installation.
Similarly, if OpenVRML is configured to be installed to the same
prefix as a Mozilla-based browser is installed on the system, "make
install" will install the Mozilla plug-in to the browser's plug-in
directory. This should be sufficient to enable support for the
"model/vrml" and "model/x3d-vrml" media types in the browser.
Entering "about:plugins" in the URL entry bar of a Mozilla-based
browser will show a listing of successfully installed plug-ins.
To run openvrml-player or the Mozilla plug-in from the build
directories, you must first start an openvrml-xembed process. Once
openvrml-xembed has been installed, D-Bus will start it automatically
as needed. Additionally, to run the plug-in from the build
directories, a symbolic link to the plug-in module "openvrml.so" must
be made in the Mozilla plug-in directory.
When running openvrml-player from the build directories, you must
specify the location of the GTK+ UI XML files using the environment
variable OPENVRML_PLAYER_UIDIR; e.g.:
$ OPENVRML_PLAYER_UIDIR=$(pwd)/src/openvrml-player \
./build/src/openvrml-player/openvrml-player
Conformance
===========
OpenVRML aspires to full conformance to the VRML97 specification. It
isn't there yet, but much of the spec is supported, and OpenVRML will
continue to get better.
Bug reports
===========
Please report any bugs you encounter using OpenVRML's bug tracking
system:
<https://sourceforge.net/apps/trac/openvrml/newticket>
Note that you will need to log into SourceForge before reporting a
bug.
Mailing lists
=============
Two mailing lists are maintained:
* <openvrml-announce@lists.sourceforge.net> is a low-traffic list for
announcments, typically regarding new releases. Subscription
instructions are at
<https://lists.sourceforge.net/lists/listinfo/openvrml-announce>
* <openvrml-develop@lists.sourceforge.net> is a forum for developers using
and working on the libraries. User feedback is welcome in this
channel. Subscription instructions are at
<https://lists.sourceforge.net/lists/listinfo/openvrml-develop>
In order to curb unsolicited commercial e-mail, openvrml-develop
permits posting only by subscribers.
Get involved
============
We're always grateful for help in improving OpenVRML. Consult the
list of active tickets:
<https://sourceforge.net/apps/trac/openvrml/report/1>
Unassigned tasks are up for grabs; but please post to the
openvrml-develop mailing list to alert others of your intention to
take a task. This helps avoid duplicated effort. If you do not see
the task you'd like to pursue listed, but you think the library could
benefit from your contribution, post a proposal to the
openvrml-develop mailing list.