Shape component

This component defines the materials and containers for geometric nodes and their appearance.

See also X3D specification of the Shape component.


1. Supported nodes

  • Shape (API reference)

    The basic X3D node for "something that can be visible and collides". Inside the Shape.geometry field place a geometry node, like IndexedFaceSet. Inside the Shape.appearance field (optionally) place the Appearance node.

  • Appearance (API reference)

    Describes the shape look (textures, material, shaders and such). Place this node inside Shape.appearance field.

  • Material (API reference)

    Describes how the shape interacts with lights. In simple terms: what is the color of the shape. Place this node inside Appearance.material field.

    Note that the rendering engine has special optimizations for the "pure emissive" materials, otherwise known as "unlit materials", that cannot be affected by lighting. If you want to use such optimized material, be sure to set to zero all these material fields:

    • ambientIntensity
    • diffuseColor
    • specularColor

    Effectively, for such material, only the emissiveColor matters.

    Pascal programmers can also use ForcePureEmissive and PureEmissive methods.

  • TwoSidedMaterial (API reference)

    The basic Material is one-sided under Gourand shading. This means that if you look at the object from behind, it will be often pure black (lighting is not applied).

    Use the TwoSidedMaterial to have a two-sided material.

    Note that you can also use Phong shading. This makes even the basic Material two-sided in Castle Game Engine.

    TODO: We don't support yet X3D separateBackColor and related properties. So TwoSidedMaterial is affected by lighting from both sides, but it always looks the same from both sides.

  • LineProperties (API reference)

    Configure line width and type (pattern). This node can be placed in Shape.lineProperties, and it affects a shape that uses a line geometry, like IndexedLineSet and LineSet. It also affects normal (filled) geometry (like IndexedFaceSet) when viewed in wireframe mode (see view3dscene "View -> Fill Mode" menu).

    We only support values 1..5 (Solid .. Dash-dot-dot) for linetype field.

    We use the GPU (OpenGL/OpenGLES) features to render lines with custom width and pattern (type).

    • This has the advantage that it's ultra-fast. Changing line width or using line pattern has virtually zero cost.

    • But the disadvantage is that we only support what the GPU (OpenGL/OpenGLES) supports.

      This particularly hurts on OpenGLES (Android, iOS), where

      1. glLineStipple is not supported (so X3D linetype field will unfortunately do nothing).
      2. Line width is limited. You can see the maxium line width on the console (output of GLInformationString), as "Max line width". Unfortunately, on many Android devices it's just 1. Which means that glLineWidth is supported, but actually completely ignored by the device.

      If you need 100% reliable line width or patterns on Android/iOS, you may need to render them differently, using filled rectangles (e.g. using IndexedFaceSet or Rectangle2D nodes). To simulate line patterns, use small repeatable textures with transparent pixels (you can set texture filtering to "NONE" using TextureProperties node to avoid smoothing the alpha channel).

  • Notes about VRML 1.0 and multiple materials: multiple materials within a single VRML 1.0 Material node work 100% correctly if you change only emissive and transparency, or only diffuse and transparency for each index. For complicated cases (like when you change diffuse, and specular, and emissive...) for each material index -> they will fail.

    VRML 2.0 and X3D removed this idea, replacing it with much simpler Color and ColorRGBA nodes, that are implemented fully.

2. TODOs

Missing and planned: