Transparency & Flattening Modes

Important Note

Outdated Version:
You are looking at an outdated documentation version for an older RapidCompact CLI distribution. If you are using a newer version of the CLI please refer to the documentation of the current CLI release version.

< previous page next page >

In this tutorial, we are going to use RapidCompact CLI to process and optimize assets with transparent parts and/or materials. In the following we will use the term opaque for all completely non-transparent materials, and transparent for all materials with any kinds of transparency, be it stored in materials descriptions or texture maps. In order to provide the best possible result according to the needs of your application, RapidCompact provides different Flattening Modes, which give the option to do a more selective merge of data (mesh, textures, materials) instead of exclusively merging all content to achieve the best performance possible (e.g., 1 drawcall per asset). We will see that it is still possible to reduce opaque meshes to one single drawcall, and why optimized assets with transparent parts or materials will always have a minimum number of two or more drawcalls, depending on the meshes and materials involved. In section Handling Transparency we go more into detail on why this is the case.

Table of Contents
The FlightHelmet model contains a transparent material and we will see what that means for the optimization process later.

Handling Transparency

 back to top

As an example file we will use the FlightHelmet asset which is shown above. You can download the glTF file here.

Let's see what RapidCompact does if we optimize the asset to 25% of the original polygons and use flattening mode "full". This can be done either directly in the command line by changing the "flattening:mode" setting, or by altering the config file under "flattening:mode". On the command line it will look like this:

     rpdx -i .\FlightHelmet.gltf -s flattening:mode full -c f:25% -e FlightHelmet-compact-full.glb

The resulting file will have only one drawcall, and all meshes and materials will be merged to use only a single, compact UV atlas. However, as you can see in the resulting model, the transparency of the glasses will not preserved:

The reason why RapidCompact does not preserve the transparency in this "full flattening" case is due to the real-time rendering pipeline not being able to deal with a mix of transparent and non-transparent parts within a single drawcall. Instead, the transparent parts must usually be rendered separately, one-by-one, and sorted back-to-front.

With RapidCompact, we are able to produce a different version that contains multiple meshes and nodes, and that will render properly in a real-time setting. The standard setting for flattening is "auto", which lets RapidCompact decide about the flattening mode - version 3 will simply flatten the asset "byOpacity". Let us simply recreate the last command, but without the --flatten command, to see the effect of the "auto" / "byOpacity" flattening mode in practice:

     rpdx -i FlightHelmet.gltf -c f:25% -e FlightHelmet-compact-auto.glb

As you may see when inspecting the resulting file, it will now have the exact same amount of faces and vertices as the previously optimized version, but it now has two drawcalls. Also, the transparency is now preserved and your rendered result should look similar to this version:

There are basically two different ways of storing transparency in the optimized models. Mostly this is dependent on how the input file's transparency is stored. If an input FBX or glTF file contains a transparency value in a material (or an OBJ file with Tr in the .mtl file), RapidCompact also preserves that material and its transparency. In many cases, however, the transparency is stored in an alpha channel of a texture map.

Flattening Modes

 back to top

To cover all sorts of possible further usage of optimized models, RapidCompact offers four unique flattening modes. Instead of merging all geometry and material information into single nodes (and hence into single drawcalls), you can specify a mode in order to preserve more of the original materials, meshes and/or hierarchy. The available flattening modes are as follows:

  • auto: Let RapidCompact decide. At this moment this is equal to the flattening mode "byOpacity".

  • byOpacity: Merges all non-transparent meshes and keeps all transparent meshes separate. Will result in 1 - n material nodes (dependant on number of transparent nodes).

  • byMaterial: Merges all meshes that share the same material ID. Will result in the same number of material nodes as in the input.

  • full: Everything is merged. Will also result in one single material node.

  • none: This mode produces the highest number of drawcalls, but preserves all nodes.
  • Notes:
  • Some formats (e.g. OBJ) do not support hierarchies or instances. For these formats, our exporters do their best to at least keep individual meshes separate.

  • The "compact" command may internally perform a flattening operation, unless flattening:mode is explicitly set to "none".

  • Flattening

    Name Type Default Valid Range Quick Description
    flattening:mode String auto {'auto', 'byOpacity', 'byMaterial', 'full', 'none'} mode to be used for flattening

    Not using any flattening has specific benefits and potential downsides as well, also depending on what mode is chosen for the specific input mesh:


  • You can continue to select and process individual nodes and their subtrees within your optimized model.

  • If your input contains instances of meshes, they can now be maintained as instances and stored/rendered efficiently.

  • If your input contains transparent meshes, your renderer will be able to render them in the correct order even after optimization.

  • Potential Downsides:

  • More complex files.

  • More drawcalls, leading to reduced rendering performance if your model has large numbers of nodes and meshes (see the next section if this worries you).

  • Some operations like decimation ( -d ) may behave in unexpected ways, e.g. create cracks between unconnected but aligned meshes. You may choose to flatten meshes before performing decimate or use the compact command instead to prevent this.

  • Flattening, Hierarchy Preservation & Performance

     back to top


    We just saw how the usage of different flattening modes can have benefits and downsides. To get a better picture what that means in terms of performance and materials of a 3D model, we will produce four different versions of the example file:

         rpdx -i FlightHelmet.gltf -s flattening:mode byOpacity -c f:25% -e FlightHelmet-compact-byOpacity.glb
         rpdx -i FlightHelmet.gltf -s flattening:mode byMaterial -c f:25% -e FlightHelmet-compact-byMaterial.glb
         rpdx -i FlightHelmet.gltf -s flattening:mode full -c f:25% -e FlightHelmet-compact-full.glb
         rpdx -i FlightHelmet.gltf -s flattening:mode none -c f:25% -e FlightHelmet-compact-none.glb

    Tip There is also an explicit --flatten command, which you can use if you only want to apply flattening, but not perform any other operation (like --compact). Make sure when working with --compact   to use the setting command -s flattening:mode arg instead of the flattening command --flatten arg . The latter will only make sense if the mesh function itself is not using flattening internally ( --compact will always flatten internally), for example using the --decimate function. After a mesh is flattened once (with --flatten or --compact), the flattening can not be reversed in the same command and the input file has to be duplicated first or re-imported if two or more flattening modes should be used in one single command on one single asset.

    Top-left: flattened "byOpacity"/"auto"; Top-right: flattened "none"; Bottom-left: flattened "full"; Bottom-right: original

    When comparing the results, we can see that each .glb file has a different number of drawcalls and nodes. Also, the result in the bottom left corner lost the transparency because of using the "full" flattening mode (we did already cover that case in the the first section).

    The other results are mostly behaving according to the syntax behind the flattening. The version reduced with "byOpacity" produces two drawcalls from two different meshes so that the transparent glasses and the opaque parts can be rendered correctly. In this case the flattening "none" version has almost the same result due to the structure of the input mesh. This might differ depending on the organization of the input mesh and hierarchy.

    Overall, we can say that using RapidCompact's standard setting (flattening mode "auto") produces results supporting and preserving transparency without compromising the performance too much. Of course, an input file with a lot of unique transparent parts will have more drawcalls than with the "full" flattening mode, but the consequences regarding performance should be still minor and usually the benefits of preserving transparency should outwheigh the additional drawcalls and nodes.

    Hierarchy Preservation:

    Let us take the models produced in the previous section and this time have a look at the glTF hierarchy in the different output files in comparison to the original hierarchy:

    From left to right: flattened "full"; flattened "byOpacity"; flattened "byMaterial"; flattened "none"; original hierarchy

    As you can see, the hierarchies of the generated results give a good overview on how RapidCompact can use a grade of flattening specifically tailored to the needs of each final application. In comparison, the flattening mode "none" will preserve the nodes and naming conventions of the original, whereas the "full" and "byOpactiy" modes will flatten either everything or all opaque nodes, respectively. Like "byOpacity", the "byMaterial" mode will usually produce a different number of nodes than given in the input model. The only difference between these two modes is that "byOpacity" will merge together all nodes that have the same opacity category (transparent or opaque), while "byMaterial" merges together all nodes that have the same material.

    Note Using the flattening mode "none" will preserve Material IDs. However if the input materials are using textures on one or multiple atlases, RapidCompact will always re-bake all materials on a number of atlases defined by the given atlas mode setting (see Atlasing Modes). In case you want to simplify the model, but preserve all original texture maps and UV coordinates, you can also use RapidCompact's UV-Preserving Simplification. In case you have to deal with tiled textures and you might want to preserve the tiling have a look at this tutorial.

    Draw Calls vs. Materials or Atlases:

    Within this tutorial, we have learned how to use RapidCompact's flattening feature to produce assets with a low number of draw calls, fitting the needs of a certain target application - for applications that require separate nodes (for example, to show, hide or transform them individually during runtime), no flattening is necessary, while others can use flattening by opacity or by material to achieve a lower number of draws, hence boosting the rendering performance. Within the next tutorial, we are going to have a look at atlasing modes, which will allow us to configure how RapidCompact creates texture atlases when creating new, optimized materials.

    < previous page next page >