From 58017a0e6a6340601a7594a2c1ca573ec5f1b95a Mon Sep 17 00:00:00 2001 From: Eliza Velasquez Date: Mon, 11 Sep 2023 14:38:58 -0700 Subject: [PATCH] Tweak documentation This is admittedly a very nitpicky change. For most of the changes, I went through the various Markdown files and added language names to the source blocks for better syntax highlighting on GitHub. It also makes it easier to copy and paste commands without copying the leading `$`. I avoided changing anything in `third_party`. Additionally, I added some instructions for compiling the Android samples on the command line and fixed some typos. --- BUILDING.md | 132 ++++++++++++++++---------------- CONTRIBUTING.md | 2 +- README.md | 2 +- android/samples/README.md | 26 +++++-- filament/README.md | 16 ++-- libs/filamat/README.md | 12 +-- site/content/posts/cocoapods.md | 4 +- tools/cmgen/README.md | 9 ++- tools/filamesh/README.md | 4 +- tools/matinfo/README.md | 4 +- tools/mipgen/README.md | 4 +- tools/specular-color/README.md | 12 +-- 12 files changed, 119 insertions(+), 108 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 9c0f4d08c95..7146b751b00 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -40,20 +40,20 @@ inside the Filament source tree. To trigger an incremental debug build: -``` -$ ./build.sh debug +```shell +./build.sh debug ``` To trigger an incremental release build: -``` -$ ./build.sh release +```shell +./build.sh release ``` To trigger both incremental debug and release builds: -``` -$ ./build.sh debug release +```shell +./build.sh debug release ``` To install the libraries and executables in `out/debug/` and `out/release/`, add the `-i` flag. @@ -76,9 +76,9 @@ The following CMake options are boolean options specific to Filament: To turn an option on or off: -``` -$ cd -$ cmake . -DOPTION=ON # Replace OPTION with the option name, set to ON / OFF +```shell +cd +cmake . -DOPTION=ON # Replace OPTION with the option name, set to ON / OFF ``` Options can also be set with the CMake GUI. @@ -102,38 +102,38 @@ script. If you'd like to run `cmake` directly rather than using the build script, it can be invoked as follows, with some caveats that are explained further down. -``` -$ mkdir out/cmake-release -$ cd out/cmake-release -$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../.. +```shell +mkdir out/cmake-release +cd out/cmake-release +cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../.. ``` Your Linux distribution might default to `gcc` instead of `clang`, if that's the case invoke `cmake` with the following command: -``` -$ mkdir out/cmake-release -$ cd out/cmake-release +```shell +mkdir out/cmake-release +cd out/cmake-release # Or use a specific version of clang, for instance /usr/bin/clang-14 -$ CC=/usr/bin/clang CXX=/usr/bin/clang++ CXXFLAGS=-stdlib=libc++ \ - cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../.. +CC=/usr/bin/clang CXX=/usr/bin/clang++ CXXFLAGS=-stdlib=libc++ \ + cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../.. ``` You can also export the `CC` and `CXX` environment variables to always point to `clang`. Another solution is to use `update-alternatives` to both change the default compiler, and point to a specific version of clang: -``` -$ update-alternatives --install /usr/bin/clang clang /usr/bin/clang-14 100 -$ update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-14 100 -$ update-alternatives --install /usr/bin/cc cc /usr/bin/clang 100 -$ update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++ 100 +```shell +update-alternatives --install /usr/bin/clang clang /usr/bin/clang-14 100 +update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-14 100 +update-alternatives --install /usr/bin/cc cc /usr/bin/clang 100 +update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++ 100 ``` Finally, invoke `ninja`: -``` -$ ninja +```shell +ninja ``` This will build Filament, its tests and samples, and various host tools. @@ -143,8 +143,8 @@ This will build Filament, its tests and samples, and various host tools. To compile Filament you must have the most recent version of Xcode installed and you need to make sure the command line tools are setup by running: -``` -$ xcode-select --install +```shell +xcode-select --install ``` If you wish to run the Vulkan backend instead of the default Metal backend, you must install @@ -152,11 +152,11 @@ the LunarG SDK, enable "System Global Components", and reboot your machine. Then run `cmake` and `ninja` to trigger a build: -``` -$ mkdir out/cmake-release -$ cd out/cmake-release -$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../.. -$ ninja +```shell +mkdir out/cmake-release +cd out/cmake-release +cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../.. +ninja ``` ### iOS @@ -164,8 +164,8 @@ $ ninja The easiest way to build Filament for iOS is to use `build.sh` and the `-p ios` flag. For instance to build the debug target: -``` -$ ./build.sh -p ios debug +```shell +./build.sh -p ios debug ``` See [ios/samples/README.md](./ios/samples/README.md) for more information. @@ -191,10 +191,10 @@ using `fsutil.exe file queryCaseSensitiveInfo`. Next, open `x64 Native Tools Command Prompt for VS 2019`, create a working directory, and run CMake in it: -``` -> mkdir out -> cd out -> cmake .. +```bat +mkdir out +cd out +cmake .. ``` Open the generated solution file `TNT.sln` in Visual Studio. @@ -204,15 +204,15 @@ target in the _Solution Explorer_ and choose _Build_ to build a specific target. For example, build the `material_sandbox` sample and run it from the `out` directory with: -``` -> samples\Debug\material_sandbox.exe ..\assets\models\monkey\monkey.obj +```bat +samples\Debug\material_sandbox.exe ..\assets\models\monkey\monkey.obj ``` You can also use CMake to invoke the build without opening Visual Studio. For example, from the `out` folder run the following command. -``` -> cmake --build . --target gltf_viewer --config Release +```bat +cmake --build . --target gltf_viewer --config Release ``` ### Android @@ -237,8 +237,8 @@ To build Android on Windows machines, see [android/Windows.md](android/Windows.m The easiest way to build Filament for Android is to use `build.sh` and the `-p android` flag. For instance to build the release target: -``` -$ ./build.sh -p android release +```shell +./build.sh -p android release ``` Run `build.sh -h` for more information. @@ -248,23 +248,23 @@ Run `build.sh -h` for more information. Invoke CMake in a build directory of your choice, inside of filament's directory. The commands below show how to build Filament for ARM 64-bit (`aarch64`). -``` -$ mkdir out/android-build-release-aarch64 -$ cd out/android-build-release-aarch64 -$ cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../../build/toolchain-aarch64-linux-android.cmake \ - -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../android-release/filament ../.. +```shell +mkdir out/android-build-release-aarch64 +cd out/android-build-release-aarch64 +cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../../build/toolchain-aarch64-linux-android.cmake \ + -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../android-release/filament ../.. ``` And then invoke `ninja`: -``` -$ ninja install +```shell +ninja install ``` or -``` -$ ninja install/strip +```shell +ninja install/strip ``` This will generate Filament's Android binaries in `out/android-release`. This location is important @@ -296,8 +296,8 @@ AAR. Alternatively you can build the AAR from the command line by executing the following in the `android/` directory: -``` -$ ./gradlew -Pcom.google.android.filament.dist-dir=../../out/android-release/filament assembleRelease +```shell +./gradlew -Pcom.google.android.filament.dist-dir=../../out/android-release/filament assembleRelease ``` The `-Pcom.google.android.filament.dist-dir` can be used to specify a different installation @@ -311,7 +311,7 @@ sure to add the newly created module as a dependency to your application. If you do not wish to include all supported ABIs, make sure to create the appropriate flavors in your Gradle build file. For example: -``` +```gradle flavorDimensions 'cpuArch' productFlavors { arm8 { @@ -353,7 +353,7 @@ started, follow the instructions for building Filament on your platform ([macOS] Next, you need to install the Emscripten SDK. The following instructions show how to install the same version that our continuous builds use. -``` +```shell cd curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.15.zip > emsdk.zip unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk @@ -364,7 +364,7 @@ source ./emsdk_env.sh After this you can invoke the [easy build](#easy-build) script as follows: -``` +```shell export EMSDK= ./build.sh -p webgl release ``` @@ -374,7 +374,7 @@ creates a `samples` folder that can be used as the root of a simple static web s cannot open the HTML directly from the filesystem due to CORS. We recommend using the emrun tool to create a quick localhost server: -``` +```shell emrun out/cmake-webgl-release/web/samples --no_browser --port 8000 ``` @@ -395,7 +395,7 @@ Some of the samples accept FBX/OBJ meshes while others rely on the `filamesh` fi generate a `filamesh ` file from an FBX/OBJ asset, run the `filamesh` tool (`./tools/filamesh/filamesh` in your build directory): -``` +```shell filamesh ./assets/models/monkey/monkey.obj monkey.filamesh ``` @@ -405,7 +405,7 @@ files for the IBL (which are PNGs containing `R11F_G11F_B10F` data) or a path to containing two `.ktx` files (one for the IBL itself, one for the skybox). To generate an IBL simply use this command: -``` +```shell cmgen -f ktx -x ./ibls/ my_ibl.exr ``` @@ -427,9 +427,9 @@ value is the desired roughness between 0 and 1. To generate the documentation you must first install `doxygen` and `graphviz`, then run the following commands: -``` -$ cd filament/filament -$ doxygen docs/doxygen/filament.doxygen +```shell +cd filament/filament +doxygen docs/doxygen/filament.doxygen ``` Finally simply open `docs/html/index.html` in your web browser. @@ -439,7 +439,7 @@ Finally simply open `docs/html/index.html` in your web browser. To try out Filament's Vulkan support with SwiftShader, first build SwiftShader and set the `SWIFTSHADER_LD_LIBRARY_PATH` variable to the folder that contains `libvk_swiftshader.dylib`: -``` +```shell git clone https://github.com/google/swiftshader.git cd swiftshader/build cmake .. && make -j @@ -454,7 +454,7 @@ Continuous testing turnaround can be quite slow if you need to build SwiftShader provide an Ubuntu-based Docker image that has it already built. The Docker image also includes everything necessary for building Filament. You can fetch and run the image as follows: -``` +```shell docker pull ghcr.io/filament-assets/swiftshader docker run -it ghcr.io/filament-assets/swiftshader ``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 955e451e093..571600da2fb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,7 +27,7 @@ again. ## Code Style -See [CodeStyle.md](/CODE_STYLE.md) +See [CODE_STYLE.md](/CODE_STYLE.md) ## Code reviews diff --git a/README.md b/README.md index 63f3a490ac7..27b5c0c7236 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ Here are all the libraries available in the group `com.google.android.filament`: iOS projects can use CocoaPods to install the latest release: -``` +```shell pod 'Filament', '~> 1.42.1' ``` diff --git a/android/samples/README.md b/android/samples/README.md index 151583bb82d..cdfc93e2e21 100644 --- a/android/samples/README.md +++ b/android/samples/README.md @@ -87,9 +87,9 @@ compile Filament's native library and Filament's AAR for this project. The easie is to install all the required dependencies and to run the following commands at the root of the source tree: -``` -$ ./build.sh -p desktop -i release -$ ./build.sh -p android release +```shell +./build.sh -p desktop -i release +./build.sh -p android release ``` This will build all the native components and the AAR required by this sample application. @@ -100,8 +100,8 @@ distribution/install directory for desktop (produced by make/ninja install). Thi contain `bin/matc` and `bin/cmgen`. Example: -``` -$ ./gradlew -Pfilament_tools_dir=../../dist-release assembleDebug +```shell +./gradlew -Pfilament_tools_dir=../../dist-release assembleDebug ``` ## Important: SDK location @@ -110,14 +110,24 @@ Either ensure your `ANDROID_HOME` environment variable is set or make sure the r contains a `local.properties` file with the `sdk.dir` property pointing to your installation of the Android SDK. -## Android Studio +## Compiling + +### Android Studio You must use the latest stable release of Android Studio. To open the project, point Studio to the `android` folder. After opening the project and syncing to gradle, select the sample of your choice using the drop-down widget in the toolbar. -## Compiling - To compile and run each sample make sure you have selected the appropriate build variant (arm7, arm8, x86 or x86_64). If you are not sure you can simply select the "universal" variant which includes all the other ones. + +### Command Line + +From the `android` directory in the project root: + +```shell +./gradlew :samples:sample-hello-triangle:installDebug +``` + +Replace `sample-hello-triangle` with your preferred project. diff --git a/filament/README.md b/filament/README.md index 1560c96135e..79ec596bde7 100644 --- a/filament/README.md +++ b/filament/README.md @@ -61,7 +61,7 @@ with the platform name, for example, `filament-20181009-linux.tgz`. Create a file, `main.cpp`, in the same directory with the following contents: -``` +```c++ #include #include @@ -91,7 +91,7 @@ Copy your platform's Makefile below into a `Makefile` inside the same directory. ### Linux -``` +```make FILAMENT_LIBS=-lfilament -lbackend -lbluegl -lbluevk -lfilabridge -lfilaflat -lutils -lgeometry -lsmol-v -lvkshaders -libl CC=clang++ @@ -109,7 +109,7 @@ clean: ### macOS -``` +```make FILAMENT_LIBS=-lfilament -lbackend -lbluegl -lbluevk -lfilabridge -lfilaflat -lutils -lgeometry -lsmol-v -lvkshaders -libl FRAMEWORKS=-framework Cocoa -framework Metal -framework CoreVideo CC=clang++ @@ -137,7 +137,7 @@ be sure to also include `matdbg.lib` in `FILAMENT_LIBS`. When building Filament from source, the `USE_STATIC_CRT` CMake option can be used to change the run-time library version. -``` +```make FILAMENT_LIBS=filament.lib backend.lib bluegl.lib bluevk.lib filabridge.lib filaflat.lib \ utils.lib geometry.lib smol-v.lib ibl.lib vkshaders.lib CC=cl.exe @@ -171,12 +171,12 @@ and invoke `nmake` instead of `make`. ### Generating C++ documentation -To generate the documentation you must first install `doxygen` and `graphviz`, then run the +To generate the documentation you must first install `doxygen` and `graphviz`, then run the following commands: -``` -$ cd filament/filament -$ doxygen docs/doxygen/filament.doxygen +```shell +cd filament/filament +doxygen docs/doxygen/filament.doxygen ``` Finally simply open `docs/html/index.html` in your web browser. diff --git a/libs/filamat/README.md b/libs/filamat/README.md index dd810042750..61d98c67677 100644 --- a/libs/filamat/README.md +++ b/libs/filamat/README.md @@ -35,7 +35,7 @@ for example, `filament-20181009-linux.tgz`. Create a file, `main.cpp`, in the same directory with the following contents: -``` +```c++ #include #include @@ -85,7 +85,7 @@ Copy your platform's Makefile below into a `Makefile` inside the same directory. ### Linux -``` +```make FILAMENT_LIBS=-lfilamat -lfilabridge -lshaders -lutils -lsmol-v CC=clang++ @@ -103,7 +103,7 @@ clean: ### macOS -``` +```make FILAMENT_LIBS=-lfilamat -lfilabridge -lshaders -lutils -lsmol-v CC=clang++ @@ -129,7 +129,7 @@ flags](https://docs.microsoft.com/en-us/cpp/build/reference/md-mt-ld-use-run-tim When building Filamat from source, the `USE_STATIC_CRT` CMake option can be used to change the run-time library version. -``` +```make FILAMENT_LIBS=lib/x86_64/mt/filamat.lib lib/x86_64/mt/filabridge.lib lib/x86_64/mt/shaders.lib \ lib/x86_64/mt/utils.lib lib/x86_64/mt/smol-v.lib CC=clang-cl.exe @@ -164,7 +164,7 @@ and invoke `nmake` instead of `make`. For simplicity, this demo doesn't do anything useful with the built material package. To use the material with Filament, pass the material package's data into a Filament Material builder: -``` +```c++ Package package = builder.build(); filament::Material* myMaterial = Material::Builder() .package(package.getData(), package.getSize()) @@ -186,7 +186,7 @@ In addition, `filamat_lite` only performs a simple text match to determine which `MaterialInputs` structure are set. The `material` input variable must also always be refered to by the name `material`. -``` +```glsl void anotherFunction(inout MaterialInputs m) { // Incorrect! The MaterialInputs is being referred to by the name "m". m.metallic = 0.0; diff --git a/site/content/posts/cocoapods.md b/site/content/posts/cocoapods.md index 25d279c9dfe..0369e3f64ad 100644 --- a/site/content/posts/cocoapods.md +++ b/site/content/posts/cocoapods.md @@ -45,8 +45,8 @@ end Then run: -``` -$ pod install +```shell +pod install ``` Close the project and then re-open the newly created HelloCocoaPods.xcworkspace file. diff --git a/tools/cmgen/README.md b/tools/cmgen/README.md index 160d48e0cd2..d3f5259e877 100644 --- a/tools/cmgen/README.md +++ b/tools/cmgen/README.md @@ -7,9 +7,9 @@ The tool can consume a HDR environment map in latlong format (equirectilinear) a ## Usage -``` -$ cmgen [options] -$ cmgen [options] +```shell +cmgen [options] +cmgen [options] ``` ## Supported input formats @@ -21,6 +21,7 @@ $ cmgen [options] ## Options +``` --help, -h Print this message --license @@ -61,4 +62,4 @@ $ cmgen [options] Roughness pre-filter into --sh-shader Generate irradiance SH for shader code - +``` diff --git a/tools/filamesh/README.md b/tools/filamesh/README.md index f39ca1e457f..ced71e413ee 100644 --- a/tools/filamesh/README.md +++ b/tools/filamesh/README.md @@ -14,8 +14,8 @@ identified by an offset and count in the index buffer. Each part can have its ow ## Usage -``` -$ filamesh source_mesh destination_mesh +```shell +filamesh source_mesh destination_mesh ``` ## Format diff --git a/tools/matinfo/README.md b/tools/matinfo/README.md index a1695351572..728ab140147 100644 --- a/tools/matinfo/README.md +++ b/tools/matinfo/README.md @@ -5,6 +5,6 @@ used for debug purpose only. ## Usage -``` -$ matinfo [options] +```shell +matinfo [options] ``` diff --git a/tools/mipgen/README.md b/tools/mipgen/README.md index e60853b219d..cd49a0ab47c 100644 --- a/tools/mipgen/README.md +++ b/tools/mipgen/README.md @@ -4,8 +4,8 @@ ## Usage -``` -$ mipgen [options] +```shell +mipgen [options] ``` Run `mipgen --help` for more information about available options. diff --git a/tools/specular-color/README.md b/tools/specular-color/README.md index 069b07b286d..94d3729a554 100644 --- a/tools/specular-color/README.md +++ b/tools/specular-color/README.md @@ -11,8 +11,8 @@ grazing angles. See Hoffman 2019, "Fresnel Equations Considered Harmful". ## Usage -``` -$ specular-color +```shell +specular-color ``` The spectral data files can be obtained from @@ -20,12 +20,12 @@ The spectral data files can be obtained from For instance, to compute the base color of gold: -``` -$ specular-color data/gold.txt +```shell +specular-color data/gold.txt ``` To set the second angle, use `-a` to specify the angle in degrees: -``` -$ specular-color -a 75 data/gold.txt +```shell +specular-color -a 75 data/gold.txt ```