Filament Code style and Formatting

Filament largely uses Android's code style, which is significantly different from the Google code style and is derived from the Java code style, but not quite.

The guiding principles of the filament code style and code formatting can be resumed as:

• no nonsense
• use your own judgement
• break the rules if it makes sense e.g.: it improves readability substantially
• use the formatting of the file you're in, even if it breaks the rules
• no nonsense

Formatting

• 4 spaces indent
• 8 spaces continuation indent
• 100 columns
• { at the end of the line
• spaces around operators and after ;
• class access modifiers are not indented
• last line of .cpp or .h file must be an empty line

for (int i = 0; i < max; i++) {
}

class Foo {
public:
protected:
private:
};

Naming Conventions

Files

• headers use the .h extension
• implementation files use the .cpp extension
• included files use the .inc extension
• class files bear the name of the class they implement
• no spaces in file names
• file names must be treated as case insensitive, i.e. it is not allowed to have several files with the same name but a different case
• #include must use fully qualified names
• use #include < > for all public (exported) headers
• use #include " " for private headers
• all public include files must reside under the include folder
• all source files must reside under the src folder
• tests reside under the test folder
• public headers of a foo library must live in a folder named foo

libfoo.so

include/foo/FooBar.h
src/FooBar.cpp
src/data.inc

#include <foo/FooBar.h>
#include "FooBarPrivate.h"

Code

• Everything is camel case except constants
• constants are uppercase and don't have a prefix
• global variables prefixed with g
• static variables prefixed with s
• private and protected class attributes prefixed with m
• static class attributes prefixed with s
• public class attributes are not prefixed
• class attributes and methods are lower camelcase

extern int gGlobalWarming;

class FooBar {
public:
    FooBar(int attributeName, int sizeInBytes)
            : mAttributeName(attributeName),
              sizeInBytes(sizeInBytes) {}

    void reallyLongMethodNameWithLotsOfArguments(bool argument1,
            int someSecondArgument, int bestArgument) {
        std::pair<bool, int> pair = {
            argument1,
            argument2,
        };
        // etc
    }

    int sizeInBytes;
private:
    int mAttributeName;
    static int sGlobalAttribute;
    static constexpr int FOO_COUNT = 10;
    enum {
        ONE, TWO, THREE
    };
};

Code Style

Files

• always include the copyright notice at the top of every file
• make sure the date is correct

/*
 * Copyright (C) 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

Headers

• always include a class' header first in the .cpp file.
• other headers are sorted in order of their layering, from most dependent to least dependent (most dependent at the top, least dependent/lower layers at the bottom).
• within a layer, headers are sorted alphabetically (with the exception of private local headers).
• strive for implementing one class per file.

Header Layering Hierarchy

Headers must be grouped and separated by exactly one blank line in the following order (top to bottom):

1. 0. Corresponding Header: #include "details/Bar.h" (the implementation's own header).
2. 0.5. Windows Cleanup Header: #include <utils/unwindows.h> (always second to undefine Windows macros, only if needed).
3. 1. Private / Local Headers: #include "PrivateStuff.h" (using " " syntax only for truly private headers located under the local module's src/ directory or its subdirectories).
4. 2. Internal Proprietary Libraries: #include <filament/Box.h>, #include <private/filament/EngineEnums.h>, #include <filaflat/MaterialChunk.h>, #include <backend/Handle.h> (all public and private includes for other proprietary libraries must use < > brackets syntax. The layering priority order of these libraries is dynamically computed based on the CMakeLists.txt target linkage graph from most dependent to least dependent).
5. 3. Third-Party Libraries: #include <tsl/robin_map.h>, #include <jni.h> (known third-party and system includes).
6. 4. C++ Standard Library: #include <algorithm> (standard C++ templates and <c...> wrappers like <cstdint>, <cstddef>).
7. 5. POSIX System Headers: #include <unistd.h> (C POSIX system headers and <sys/...> headers, placed below C++ standard but above legacy C standard).
8. 6. C Standard Library: #include <stddef.h> (legacy system headers ending in .h).

Private / Local Includes Formatting (Layer 1)

To maximize readability for local quoted includes:

• Flat-First Sorting: Flat/top-level files (without a directory prefix, e.g., "Allocators.h") are sorted first. Files nested inside subdirectories (e.g., "components/Foo.h") are sorted second.
• Sub-Directory Spacing: includes are grouped by their sub-directory path prefix, with exactly one blank line separating different sub-directory groups.

Sorting the headers is important to help catching missing #include directives.

/*
 * Copyright (C) 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

// Bar.cpp

// 0. Corresponding header
#include <foo/Bar.h>

// 0.5. Windows Cleanup
#include <utils/unwindows.h>

// 1. Private / local headers (grouped by subdirectory prefix, flat first)
#include "Allocators.h"

#include "components/LightManager.h"
#include "components/RenderableManager.h"

#include "details/Engine.h"
#include "details/Skybox.h"

// 2. Internal library headers (sorted by topological dependencies: filaflat above backend)
#include <private/filament/EngineEnums.h>
#include <filament/Box.h>

#include <filaflat/MaterialChunk.h>

#include <backend/Handle.h>

#include <private/utils/Tracing.h>
#include <utils/Allocator.h>

#include <math/vec3.h>

// 3. Third-party
#include <tsl/robin_map.h>

// 4. C++ Standard Library
#include <algorithm>
#include <cstddef>
#include <cstdint>
#include <utility>

// 5. POSIX / System headers
#include <unistd.h>
#include <sys/stat.h>

// 6. C Standard Library
#include <stddef.h>
#include <stdint.h>

Automatic Header Formatting Tool

An official script is available in the repository to automatically format and sort C++ include blocks in accordance with these rules:

./tools/reorganize_headers.py <file_or_directory>

To see what changes would be made without modifying the files, use the --dry-run option:

./tools/reorganize_headers.py --dry-run <file_or_directory>

Note: The tool has safety checks built-in and will automatically skip any files with inline preprocessor conditionals (#if, #ifdef, etc.) or nested code statements inside their include block to prevent compilation regressions.

• STL limited in filament public headers to:
  • array
  • initializer_list
  • iterator
  • limits
  • optional
  • type_traits
  • utility
  • variant

For libfilament the rule of thumb is that STL headers that don't generate code are allowed (e.g. type_traits), conversely containers and algorithms are not allowed. There are exceptions such as array. See above for the full list.

• The following STL headers are banned entirely, from public and private headers as well as implementation files:
  • iostream

Strings

• Never use std::string in the Filament core renderer. Prefer utils::CString or std::string_view.
• When using std::string in tools, always include the std:: qualifier to disambiguate it from other string types.

Misc

• Use auto only when the type appears on the same line or with iterators and lambdas.

auto foo = new Foo();
for (auto& i : collection) { }