
Frequently Asked Questions for Coin
===================================

Last Updated:
$Date: 2002/09/17 12:06:47 $

For answers to common Open Inventor programming issues not covered in this
FAQ, take a look at the FAQs directory in the SoGuiExamples archive.

For answers to common qquestions regarding the SoQt library, see the FAQ
in the SoQt source archive.

The most up-to-date version of this file can always be found at
http://source.coin3d.org/Coin/FAQ


Index
=====

0: Legal Issues
  Q1: Coin is under the GNU Lesser General Public License ("LGPL").
      That means I can use it in my proprietary, commercially sold
      application, right?

  Q2: Is it possible to use the Coin library without the restrictions
      of the GNU LGPL?

  Q3: How can you sell a "Professional Edition License" when the
      library is released under the GNU LGPL? Wouldn't that be
      disallowed by the GNU LGPL?

1: Extensions and Ports
  Q1: Are there plans for making Coin multi-thread safe?

  Q2: Can Coin do multi-pipe rendering?

  Q3: Can I do volume rendering with Coin?

  Q4: Does Coin support VRML97?

  Q5: Is there an MS Visual C++ project I can use to build Coin?

  Q6: Is there a Coin port for Mac OS X/Darwin?

2: Common Problems
  Q1: <Node>::classTypeId != SoType::badType() && "You forgot init()"?

  Q2: Why doesn't it work properly to render the same scene graph in two
      different windows?

  Q3: Why does my Visual C++ program using Coin work for debug builds but
      not for release builds?

  Q4: I try to change the SoText2/SoText3 font, but nothing happens.
      Why, oh why?

  Q5: Where does the SoGuiExamples module install the programs?

  Q6: Why can't any of the transparency modes be perfect?

3: Other Hows and Whys
  Q1: Why is the .so-version 20 for Coin 1.0?


Section 0. Legal Issues
=======================

Q0.1: Coin is under the GNU Lesser General Public License ("LGPL").
      That means I can use it in my proprietary, commercially sold
      application, right?

A:    Yes, given that the rules of the GNU LGPL is followed, of course.

      You should for instance be aware that the GNU LGPL places
      certain restrictions on how you can distribute your application
      executable. Static linking against the library is difficult to
      do while still heeding the LGPL: the software end-user can
      demand that the vendor provides him with the means to re-link
      the application against new versions of the library.

      In practical terms, that would probably mean distributing the
      compiler-generated object-files to the user -- which is likely
      to cause a maintenance nightmare.

      Another restriction set up by the GNU LGPL is that you or your
      company also implicitly takes on the responsibility of making
      the full Coin sourcecode available for any user who requests it.

      Yet another restriction is that when you add extension code or
      make changes to Coin or one of our other LGPL'ed libraries, like
      SoQt, the GNU LGPL will usually force you to release those
      extensions publicly -- no matter what size they are and effort
      they represent on your's or your company's behalf.


      For these reasons, the distribution and availability of the Coin
      library under the GNU LGPL is primarily meant to be a service
      for those who write other Free Software libraries or
      applications. If you write proprietary software and would like
      to use the Coin library, see the next question.

      Important note: from version 2.0.0 and onwards, the Coin library
      will no longer be released under the GNU LGPL. Future Free
      Software releases will be done under the GNU GPL.


Q0.2: Is it possible to use the Coin library without the restrictions
      of the GNU LGPL?

A:    Yes, as a service for those who would like to use the Coin library
      in proprietary software, we at Systems in Motion offer the "Coin
      Professional Edition License" which buys developers that are
      license holders the option to use the library with no strings
      attached.

      By "no strings attached", we of course mean that you as a
      proprietary software developer would not have to obey the
      restrictions of the GNU LGPL, as you would use the Coin library
      under our "Professional Edition" license instead.

      The Coin Professional Edition License additionally covers
      other libraries in the "Coin family" for no extra cost,
      including all the GUI toolkits (SoQt, SoWin, SoGtk, SoXt) and
      Systems in Motion's 3D file format libraries Dime and Profit.

      See <URL:http://www.coin3d.org> for more information about the
      details of these libraries.

      Prioritized support services is also part of the package -- your
      support requests will be sent straight to the top of the
      todo-stack of our developers. The developers used as first-tier
      support for our Coin Professional Edition License holders are
      the same people who have written all the sourcecode of the
      library in the first place, so you will be in very good hands.

      We take pride in giving our customers excellent support, and
      since the Coin library is what our developers love to work with,
      it's given with a smile.  :-)

      Oh, and one additional benefit from being a Coin Professional
      Edition License holder: you are allowed to cut'n'paste from our
      sourcecode and use it in your own applications without having to
      worry about licensing issues. This is for instance very
      convenient when writing extensions components for Coin, like new
      nodes or action types.

      You may also cut'n'paste code from all our example programs in
      the same manner (these are originally under the GNU GPL, by the
      way).


Q0.3: How can you sell a "Professional Edition License" when the
      library is released under the GNU LGPL? Wouldn't that be
      disallowed by the GNU LGPL?

A:    Systems in Motion can do this dual licensing "trick" with Coin
      because we are full copyright holders -- ie we own every single
      line of code written for the Coin library. Therefore we are able
      to license the Coin library both as Free Software aswell as
      under a special purpose license for proprietary software
      vendors. (If you are familiar with TrollTech's "Qt" library,
      they use the same strategy.)



Section 1. Extensions and Ports
===============================

Q1.1:   Are there plans for making Coin multi-thread safe?

A:      Yes.  The wheels are in motion on this one.  It is not happening
        for the Coin 1.* branch though.


Q1.2:   Can Coin do multi-pipe rendering?

A:      Not yet.  We certainly want to support this.  Note that this
        feature depends on having achieved multi-thread safety for
        Coin first.


Q1.3:   Can I do volume rendering with Coin?

A:      There are no volume rendering extensions for Coin yet.  Support for
        3D textures, which is a prerequisite for proper volume rendering
        support, was recently implemented in the Coin development branch
        and will be available from release 2.0 of Coin.

        Exactly when fullblown volume rendering is going to be implemented
        is in the blue, but it is functionality we see a demand for, so we
        are certainly interested in adding support for it, but there are
        no concrete plans for putting resources on this currently.


Q1.4:   Does Coin support VRML97?

A:      Coin 1.* does not support VRML97.  Coin 2.0 and upwards will support
        it.  The development repository for Coin already contains code for a
        great deal of the VRML97 standard.  It is not 100% complete yet
        though.


Q1.5:   Is there an MS Visual C++ project I can use to build Coin?

A:      Not currently.  We will probably support this sometime in the
        future, but it will only happen when we can have the project
        files generated automatically from the Automake setup.

        Other people have have done this manually by first
        pre-generating the autogenerated files on a Cygwin system, and
        then set up a project file for all the Coin source files
        (excluding all the all.cpp files and this list of "includes":

          engines/lex.so_eval.c
          misc/SoGLFaceSetTemplate.cpp
          misc/SoGLLineSetTemplate.cpp
          misc/SoGLTristripTemplate.cpp
          misc/SoGLindexedLineSetTemplate.cpp
          misc/SoGLnonindexedFaceSetTemplate.cpp
          misc/SoGLnonindexedTristripSetTemplate.cpp
          misc/SoGLqmeshTemplate.cpp

        If you don't feel like setting this up your self, someone at
        the coin-discuss mailing list may be willing to redistribute
        their setup.  Check the coin-discuss@coin3d.org mailing list
        archive first for whether this has been asked recently, and
        then ask if not.  The archive is located at
        <URL:http://auto.coin3d.org/coin-discuss/>.


Q1.6:   Is there a Coin port for Mac OS X/Darwin?

A:      Coin configures and compiles on Mac OS X, but there is currently no
        SoMac library available.

        For a window binding, there are still at least three options:
        1) use Coin with GLUT, 2) manage the GL context manually, 3)
        use the port of the Qt multiplatform library -- see
        <URL:http://www.trolltech.com>.


Section 2. Common Problems
==========================

Q2.1:   <Node>::classTypeId != SoType::badType() && "You forgot init()"?

A:      If you get this assert, it means the run-time type system in
        Coin was not initialized at the time a <Node> object is constructed.

        This can happen for several reasons:
        - you haven't called SoDB::init() yet when you construct a node.
        - you have a global node that is constructed automatically on startup
          before main is run.
        - [VC++] you have linked multiple instances of the Coin library into
          your application or the Coin library and the application or some
          other library are using different C library instances.

        In the case of not calling SoDB::init(), it is clearly stated on
        page 36 of The Inventor Mentor that "SoDB::init() must be the first
        Inventor call you make.".

        "But this works with SGI Inventor", I hear you say...  Actually,
        that is just pure luck.  Try e.g. creating a new SoBlinker node,
        and you will see your application going down in flames.


Q2.2:   Why doesn't it work properly to render the same scene graph in two
        different windows?

A:      The reason is probably that the two windows do not share the same
        GL context, but the render actions are not set up with different
        cache contexts.  Use two different values with
        SoGLRenderAction::setCacheContext() for the two windows' render
        actions.  Example follows:

          for (int i=0; i < NR_VIEWERS; i++) {
            SoGLRenderAction * renderaction = window[i]->getGLRenderAction();
        #ifdef __COIN__
          /* In Coin, we have added an extension to SoGLCacheContextElement
             for getting a _guaranteed_ unique number for the cache contexts.
             That the original Inventor API is missing a function like this
             should be considered an ugly flaw in the design. */
            uint32_t uniqcc = SoGLCacheContextElement::getUniqueCacheContext();
        #else // SGI or TGS Inventor
          /* Use a "pseudo-random" number and cross your fingers that it's
             unique, since there's no decent method in the API from which
             the application programmer can get a unique cache context id. */
            uint32_t uniqcc = 19720408 + i;
        #endif // SGI / TGS Inventor
            renderaction->setCacheContext(uniqcc);
          }

        This is taken care of automatically by Systems in Motion's
        SoQt / SoGtk / SoXt / SoWin libraries, so you shouldn't have
        to worry about it unless you are making your own GUI binding
        to Coin from scratch.


Q2.3:   Why does my Visual C++ program using Coin work for debug builds but
        not for release builds?

A:      The MS Visual C++ compiler changes behaviour when you change between
        DEBUG and RELEASE mode.  Initialization of variables is one thing
        in particular you should look at - debug compilation will cause
        all variables to be initialized to zero, while they will have random
        values for release builds.

        There are of course other possible causes as well.


Q2.4:   I try to change the SoText2/SoText3 font, but nothing happens.
        Why, oh why?

A:      The font support is currently limited to a hardcoded font for both
        Text2 and Text3.  Better to have one font than none at all.

        Implementing support for the FreeType library for this is on our
        TODO list.


Q2.5:   Where does the SoGuiExamples module install the programs?

A:      They are not installed.  The programs are just examples, and do not
        belong with the installed executables on a system.  They are built
        in the build dir, and are intended to be run from there.


Q2.6:   Why can't any of the transparency modes be perfect?

A:      (First of all, read the documentation on
        SoGLRenderAction::TransparencyMode.)

        Doing correct rendering of multiple transparent objects often
        fails because, to be 100% correct, all polygons needs to be
        rendered in sorted order, and none of the polygons can
        intersect with other polygons.

        Now, how expensive would it be to check for intersecting
        polygons and just split those into non-intersecting ones?  Why
        is that so hard that it's not done?

        It's not really that hard, but it's very difficult to do it
        fast.  It's basically a O(n^2) problem (n = number of
        triangles in the scene), since you for every triangle have to
        test if it intersects any of the other triangles.

        Of course it's possible to optimize this by using an oct tree
        structure or something, but in a dynamic scene graph you have
        to build/change this oct tree structure every frame, which can
        be quite expensive.  Also, rendering will be much slower,
        since you can no longer use the tight rendering loops we now
        use. The steps needed to do correct transparency rendering is:

          1. Generate and store all triangles, using SoCallbackAction.

          2. Clip all intersecting triangles, producing any number of
             new triangles.

          3. Sort all triangles on distance to projection plane.

          4. For each triangle
            4.1. set correct OpenGL rendering state (material, texture, etc)
            4.2. render triangle

        You also risk lots of expensive OpenGL state changes, since
        you might have to change texture/material for every triangle
        in 4.1. This is a very slow operation in OpenGL.

        All of the above steps can be done from application code, so
        it's not absolutely necessary to have this as a Coin feature.

        It /might/ be added as a feature of the library sometime in
        the future, as having the option of choosing correct but
        (possibly very) slow rendering over flawed transparency
        rendering would probably be worthwhile for many users.


Section 3. Other Hows and Whys
==============================

Q3.1:   Why is the .so-version 20 for Coin 1.0?

A:      This was done to keep the artificial mapping we have constructed
        between the release version number and ABI interface version of Coin
        as simple as possible.  We have this mapping because we plan to
        do parallell development of Coin 1.0 and Coin 2.0 at the same time
        because Coin 1.0 has special status as the Open Inventor 2.1
        compatibility release.

        Keep in mind that .so-version numbers and release version numbers
        really do not have anything to do with each other in the first place.

        When you release a new major version of a library, you usually
        break compatibility with earlier versions of the library.  When you
        change the API/ABI of a library, you increment the interface number
        to indicate that the library has a new interface.  Since we want to
        continue development of Coin 1.0 after Coin 2.0 is released, we need
        to reserve space for future Coin 1.x releases, and set the Coin 2.0
        interface number after the reserved space.  We decided 20 interface-
        numbers would suffice for each major version of the Coin library,
        and the simplest equation for finding the interface number became
        major*20+minor.

        Incidentally, a lot of platforms (Linux included) calculate the
        .so-number by taking the interface number and subtracting the age,
        and the age is the same as the minor release version number for
        Coin.  This will make the .so-number stay at 20 for the whole 1.x
        series and similarly stay at 40 for the whole 2.x series, which of
        course looks silly, but that's the way it is.

        See also the Libtool manual, section about Versioning.  It's the
        same system, except that we have added reserved space in our scheme.

--
