diff --git a/BUILDING.md b/BUILDING.md index 86d64decf1..64bfbf5b88 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -62,6 +62,11 @@ force a clean build by adding the `-c` flag in that case. To install the libraries and executables in `out/debug/` and `out/release/`, add the `-i` flag. The script offers more features described by executing `build.sh -h`. +For more specialized options, please also consider the following pages: + - `-d`: [`matdbg`](https://google.github.io/filament/dup/matdbg.html) + - `-t`: [`fgviewer`](https://google.github.io/filament/dup/fgviewer.html) + - `-b` and `-y`: [ASAN/UBSAN builds](https://google.github.io/filament/notes/asan_ubsan.html) + ### Filament-specific CMake Options The following CMake options are boolean options specific to Filament: diff --git a/CMakeLists.txt b/CMakeLists.txt index c21fcb0410..ebac70e970 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -753,12 +753,61 @@ function(combine_static_libs TARGET OUTPUT DEPS) endfunction() # ================================================================================================== -# Configuration for CMAKE_CROSSCOMPILING. +# Configuration importing/exporting prebuilt "/tools" executables # ================================================================================================== + +# In certain cases, we want the ability to separate the build type/flags (release, debug) of tools +# (matc, resgen, etc...) from filament. Cross compilation is one such case (e.g. building material +# with matc running on host while building filament for Android) [1]. Another example is when client +# wants to enable ASAN for filament but not the tool [2]. +# +# Here are the varibles that are used to determine behavior is such flows: +# - CMAKE_CROSSCOMPILING : Set by cmake to indicate the build's target platform is different +# from the host platform. +# - IMPORT_EXECUTABLES_DIR : This is the directory containing the /ImportExecutables-type.cmake +# which are then included in other CMakeLists.txt to enable finding targets that have been +# prebuilt. This is set by the client in their `cmake` invocation. +# - IMPORT_EXECUTABLES : Path to a file to for 1) exporting the prebuilt targets or 2) +# importing a previously exported targets. (Used internally and should not be set by client). +# - FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR : A path set by the client to indicate that +# they wish to export the tools as prebuilts, and the corresponding targets will be recorded +# in a cmake file (i.e IMPORT_EXECUTABLES). IMPORT_EXECUTABLES will be set relative to the the +# given path. This will set FILAMENT_EXPORT_PREBUILT_EXECUTABLES=ON. +# - FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR : A path set by the client to indicate that they wish +# to import the tools as prebuilts from a .cmake file. The location (IMPORT_EXECUTABLES) of the +# file is relative to the path given. This will set FILAMENT_IMPORT_PREBUILT_EXECUTABLES=ON. +# - IMPORT_PREBUILT_EXECUTABLES and EXPORT_PREBUILT_EXECUTABLES are internal booleans set to +# ON based on the prescence of FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR and +# FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR. +# +# In conclusion, for cases +# - [1] (crosscompiling), the client must set IMPORT_EXECUTABLES_DIR for both when they are building +# the tools and when they are building the target-platform filament. +# - [2] (all other instances), the client must set FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR in +# the prebuilt exporting step, and set FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR in the importing +# step. + +# TODO: Fold the cross compilation case into the more general FILAMENT_IMPORT/EXPORT variables. + +if (FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR) + set(FILAMENT_EXPORT_PREBUILT_EXECUTABLES ON) + set(IMPORT_EXECUTABLES_DIR ${FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR}) +endif() + +if (FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR) + set(FILAMENT_IMPORT_PREBUILT_EXECUTABLES ON) + set(IMPORT_EXECUTABLES_DIR ${FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR}) +endif() + if (WEBGL) set(IMPORT_EXECUTABLES ${FILAMENT}/${IMPORT_EXECUTABLES_DIR}/ImportExecutables-Release.cmake) else() - set(IMPORT_EXECUTABLES ${FILAMENT}/${IMPORT_EXECUTABLES_DIR}/ImportExecutables-${CMAKE_BUILD_TYPE}.cmake) + if (FILAMENT_EXPORT_PREBUILT_EXECUTABLES OR FILAMENT_IMPORT_PREBUILT_EXECUTABLES) + set(IMPORT_EXECUTABLES_BUILD_TYPE Prebuilt) + else() + set(IMPORT_EXECUTABLES_BUILD_TYPE ${CMAKE_BUILD_TYPE}) + endif() + set(IMPORT_EXECUTABLES ${FILAMENT}/${IMPORT_EXECUTABLES_DIR}/ImportExecutables-${IMPORT_EXECUTABLES_BUILD_TYPE}.cmake) endif() # ================================================================================================== @@ -917,6 +966,6 @@ if (IS_HOST_PLATFORM) endif() # Generate exported executables for cross-compiled builds (Android, WebGL, and iOS) -if (NOT CMAKE_CROSSCOMPILING) +if ((NOT CMAKE_CROSSCOMPILING AND NOT FILAMENT_IMPORT_PREBUILT_EXECUTABLES) OR FILAMENT_EXPORT_PREBUILT_EXECUTABLES) export(TARGETS matc cmgen filamesh mipgen resgen uberz glslminifier FILE ${IMPORT_EXECUTABLES}) endif() diff --git a/NEW_RELEASE_NOTES.md b/NEW_RELEASE_NOTES.md index be2fc3ce15..3494d293eb 100644 --- a/NEW_RELEASE_NOTES.md +++ b/NEW_RELEASE_NOTES.md @@ -7,5 +7,4 @@ appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md). ## Release notes for next branch cut -- materials: Add a new API getParameterTransformName that will return the value of the transformName field of a sampler -parameter. [⚠️ **Recompile Materials**] \ No newline at end of file +- Metal: Add support for the `SwapChain::CONFIG_MSAA_4_SAMPLES` flag. \ No newline at end of file diff --git a/README.md b/README.md index c64b189f74..9271819274 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ repositories { } dependencies { - implementation 'com.google.android.filament:filament-android:1.66.1' + implementation 'com.google.android.filament:filament-android:1.66.2' } ``` @@ -51,7 +51,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.66.1' +pod 'Filament', '~> 1.66.2' ``` ## Documentation diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 5b4ff993b7..61ea84f209 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -7,6 +7,11 @@ A new header is inserted each time a *tag* is created. Instead, if you are authoring a PR for the main branch, add your release note to [NEW_RELEASE_NOTES.md](./NEW_RELEASE_NOTES.md). +## v1.67.0 + +- materials: Add a new API getParameterTransformName that will return the value of the transformName field of a sampler +parameter. [⚠️ **Recompile Materials**] + ## v1.66.2 diff --git a/android/filament-android/CMakeLists.txt b/android/filament-android/CMakeLists.txt index 8086541e2b..94ad5ef6a5 100644 --- a/android/filament-android/CMakeLists.txt +++ b/android/filament-android/CMakeLists.txt @@ -51,10 +51,6 @@ add_library(bluevk STATIC IMPORTED) set_target_properties(bluevk PROPERTIES IMPORTED_LOCATION ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libbluevk.a) -add_library(vkshaders STATIC IMPORTED) -set_target_properties(vkshaders PROPERTIES IMPORTED_LOCATION - ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libvkshaders.a) - if (FILAMENT_SUPPORTS_WEBGPU) add_library(webgpu_dawn STATIC IMPORTED) set_target_properties(webgpu_dawn PROPERTIES IMPORTED_LOCATION @@ -165,7 +161,6 @@ target_link_libraries(filament-jni PRIVATE $<$:matdbg> PRIVATE $<$:filamat> PRIVATE $<$:bluevk> - PRIVATE $<$:vkshaders> PRIVATE $<$:smol-v> PRIVATE $<$:webgpu_dawn> ) diff --git a/android/gradle.properties b/android/gradle.properties index 28b3600d9e..1f276c49a9 100644 --- a/android/gradle.properties +++ b/android/gradle.properties @@ -1,5 +1,5 @@ GROUP=com.google.android.filament -VERSION_NAME=1.66.1 +VERSION_NAME=1.66.2 POM_DESCRIPTION=Real-time physically based rendering engine for Android. diff --git a/build.sh b/build.sh index c3cd3c9379..03cd17440e 100755 --- a/build.sh +++ b/build.sh @@ -77,6 +77,10 @@ function print_help { echo " meant for building the samples." echo " -P" echo " Enable perfetto traces on Android. Disabled by default on the Release build, enabled otherwise." + echo " -y build_type" + echo " Build the filament dependent tools (matc, resgen) separately from the project. This will set" + echo " the tools as prebuilts that filament target will then use to build. The built_type option" + echo " (debug|release) is meant to indicate the type of build of the resulting prebuilts." echo "" echo "Build types:" echo " release" @@ -217,6 +221,11 @@ OSMESA_OPTION="" IOS_BUILD_SIMULATOR=false BUILD_UNIVERSAL_LIBRARIES=false +ISSUE_SPLIT_BUILD=false +SPLIT_BUILD_TYPE="" +PREBUILT_TOOLS_DIR="" +IMPORT_EXECUTABLES_DIR_OPTION="-DIMPORT_EXECUTABLES_DIR=out" + BUILD_GENERATOR=Ninja BUILD_COMMAND=ninja BUILD_CUSTOM_TARGETS= @@ -242,6 +251,37 @@ function build_clean_aggressive { git clean -qfX android } +function build_tools_for_split_build { + local build_type_arg=$1 + local lc_build_type=$(echo "${build_type_arg}" | tr '[:upper:]' '[:lower:]') + PREBUILT_TOOLS_DIR="out/prebuilt-tools-${lc_build_type}" + + echo "Building tools for split build (${lc_build_type}) in ${PREBUILT_TOOLS_DIR}..." + mkdir -p "${PREBUILT_TOOLS_DIR}" + + pushd "${PREBUILT_TOOLS_DIR}" > /dev/null + + local lc_name=$(echo "${UNAME}" | tr '[:upper:]' '[:lower:]') + local architectures="" + if [[ "${lc_name}" == "darwin" ]]; then + if [[ "${BUILD_UNIVERSAL_LIBRARIES}" == "true" ]]; then + architectures="-DCMAKE_OSX_ARCHITECTURES=arm64;x86_64" + fi + fi + + cmake \ + -G "${BUILD_GENERATOR}" \ + -DFILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR=${PREBUILT_TOOLS_DIR} \ + -DCMAKE_BUILD_TYPE="${build_type_arg}" \ + ${WEBGPU_OPTION} \ + ${architectures} \ + ../.. + + ${BUILD_COMMAND} ${WEB_HOST_TOOLS} + + popd > /dev/null +} + function build_desktop_target { local lc_target=$(echo "$1" | tr '[:upper:]' '[:lower:]') local build_targets=$2 @@ -265,7 +305,7 @@ function build_desktop_target { if [[ ! -d "CMakeFiles" ]] || [[ "${ISSUE_CMAKE_ALWAYS}" == "true" ]]; then cmake \ -G "${BUILD_GENERATOR}" \ - -DIMPORT_EXECUTABLES_DIR=out \ + ${IMPORT_EXECUTABLES_DIR_OPTION} \ -DCMAKE_BUILD_TYPE="$1" \ -DCMAKE_INSTALL_PREFIX="../${lc_target}/filament" \ ${EGL_ON_LINUX_OPTION} \ @@ -331,7 +371,7 @@ function build_webgl_with_target { source "${EMSDK}/emsdk_env.sh" cmake \ -G "${BUILD_GENERATOR}" \ - -DIMPORT_EXECUTABLES_DIR=out \ + ${IMPORT_EXECUTABLES_DIR_OPTION} \ -DCMAKE_TOOLCHAIN_FILE="${EMSDK}/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake" \ -DCMAKE_BUILD_TYPE="$1" \ -DCMAKE_INSTALL_PREFIX="../webgl-${lc_target}/filament" \ @@ -404,7 +444,7 @@ function build_android_target { if [[ ! -d "CMakeFiles" ]] || [[ "${ISSUE_CMAKE_ALWAYS}" == "true" ]]; then cmake \ -G "${BUILD_GENERATOR}" \ - -DIMPORT_EXECUTABLES_DIR=out \ + ${IMPORT_EXECUTABLES_DIR_OPTION} \ -DCMAKE_BUILD_TYPE="$1" \ -DFILAMENT_NDK_VERSION="${FILAMENT_NDK_VERSION}" \ -DCMAKE_INSTALL_PREFIX="../android-${lc_target}/filament" \ @@ -638,7 +678,7 @@ function build_ios_target { if [[ ! -d "CMakeFiles" ]] || [[ "${ISSUE_CMAKE_ALWAYS}" == "true" ]]; then cmake \ -G "${BUILD_GENERATOR}" \ - -DIMPORT_EXECUTABLES_DIR=out \ + ${IMPORT_EXECUTABLES_DIR_OPTION} \ -DCMAKE_BUILD_TYPE="$1" \ -DCMAKE_INSTALL_PREFIX="../ios-${lc_target}/filament" \ -DIOS_ARCH="${arch}" \ @@ -810,7 +850,7 @@ function check_debug_release_build { pushd "$(dirname "$0")" > /dev/null -while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:P" opt; do +while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:Py:" opt; do case ${opt} in h) print_help @@ -979,6 +1019,20 @@ while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:P" opt; do ;; X) OSMESA_OPTION="-DFILAMENT_OSMESA_PATH=${OPTARG}" ;; + y) + ISSUE_SPLIT_BUILD=true + SPLIT_BUILD_TYPE=${OPTARG} + case $(echo "${SPLIT_BUILD_TYPE}" | tr '[:upper:]' '[:lower:]') in + debug|release) + ;; + *) + echo "Unknown build type for -y: ${SPLIT_BUILD_TYPE}" + echo "Build type must be one of [debug|release]" + echo "" + exit 1 + ;; + esac + ;; \?) echo "Invalid option: -${OPTARG}" >&2 echo "" @@ -1013,6 +1067,13 @@ done validate_build_command +if [[ "${ISSUE_SPLIT_BUILD}" == "true" ]]; then + # Capitalize first letter of SPLIT_BUILD_TYPE + SPLIT_BUILD_TYPE_CAPITALIZED="$(echo ${SPLIT_BUILD_TYPE:0:1} | tr '[:lower:]' '[:upper:]')${SPLIT_BUILD_TYPE:1}" + build_tools_for_split_build "${SPLIT_BUILD_TYPE_CAPITALIZED}" + IMPORT_EXECUTABLES_DIR_OPTION="-DFILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR=${PREBUILT_TOOLS_DIR}" +fi + if [[ "${ISSUE_CLEAN}" == "true" ]]; then build_clean fi diff --git a/docs/dup/bluevk.html b/docs/dup/bluevk.html index 4a0766f07f..7b3ef28175 100644 --- a/docs/dup/bluevk.html +++ b/docs/dup/bluevk.html @@ -180,7 +180,7 @@ rm -r Vulkan-Headers-1.3.232 v1.3.232.zip - @@ -194,7 +194,7 @@ rm -r Vulkan-Headers-1.3.232 v1.3.232.zip - diff --git a/docs/dup/building.html b/docs/dup/building.html index cfcd89a1c2..9fe674ea3e 100644 --- a/docs/dup/building.html +++ b/docs/dup/building.html @@ -200,6 +200,12 @@ inside the Filament source tree.

force a clean build by adding the -c flag in that case.

To install the libraries and executables in out/debug/ and out/release/, add the -i flag. The script offers more features described by executing build.sh -h.

+

For more specialized options, please also consider the following pages:

+

Filament-specific CMake Options

The following CMake options are boolean options specific to Filament:

    diff --git a/docs/dup/fgviewer.html b/docs/dup/fgviewer.html new file mode 100644 index 0000000000..95e7963e05 --- /dev/null +++ b/docs/dup/fgviewer.html @@ -0,0 +1,345 @@ + + + + + + fgviewer - Filament + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + + + + + + + + + + +
    + +
    + + + + + + + + +
    +
    +

    fgviewer

    +
      +
    1. Capabilities
      2. +
    2. Setup for Desktop
      3. +
    3. Setup for Android
      4. +
    4. Debugger Usage
      5. +
    5. Architecture Overview
      6. +
    6. C++ Server
      7. +
    7. JavaScript Client
      8. +
    8. HTTP Requests
      9. +
    9. Wish List
      10. +
    +

    Capabilities

    +

    fgviewer is a library and web application for real-time visualization of the frame graph in Filament. +It displays active passes and resource usage, providing insights into the rendering pipeline.

    +

    Setup for Desktop

    +

    When using the easy build script, include the -t argument. For example:

    +
    ./build.sh -ft debug gltf_viewer
+
    +

    The t enables a CMake option called FILAMENT_ENABLE_FGVIEWER and the f ensures that CMake gets +re-run so that the option is honored.

    +

    Next, set an environment variable as follows. In Windows, use set instead of export.

    +
    export FILAMENT_FGVIEWER_PORT=8050
+
    +

    Next, launch any app that links against a debug build of a Filament and point your web browser to +http://localhost:8050. Skip ahead to Debugger Usage.

    +

    Setup for Android

    +

    Rebuild Filament for Android after enabling a CMake option called FILAMENT_ENABLE_FGVIEWER. Note that +CMake is invoked from several places for Android (both gradle and our easy build script), so one +pragmatic and reliable way of doing this is to simply hack CMakeLists.txt and +filament-android/CMakeLists.txt by unconditionally setting FILAMENT_ENABLE_FGVIEWER to ON.

    +

    After rebuilding Filament with the option enabled, ensure that internet permissions are enabled in +your app by adding the following into your manifest as a child of the <manifest> element.

    +
    <uses-permission android:name="android.permission.INTERNET" />
+
    +

    Now launch your app as usual. The Filament Engine sets up a server that is hardcoded to listen to +port 8085. Next, you will need to forward your device's TCP port 8085 to your host port of choice. +For example, to forward the fgviewer server on your device to port 8085 on your host machine, do the +following:

    +
    adb forward tcp:8085 tcp:8085
+
    +

    This lets you go to http://localhost:8085 in Chrome on your host machine.

    +

    Debugger Usage

    +

    After opening the fgviewer page in your browser, you can see the active views are on the left panel. +Then you can select any of them to see the active passes and resources for that view.

    +

    + +

    +

    Architecture Overview

    +

    + +

    +

    The fgviewer library has two parts: a C++ server and a JavaScript client. The C++ server is +responsible for instancing a civetweb context that handles HTTP requests. The +JavaScript client is a small web app that contains a view into an in-browser database of framegraphs.

    +

    When a new connection is established, the client asks the server for a list of framegraphs +in order to populate its in-browser database. If the connection is lost (e.g. if the app crashes), +then the database stays intact and the web app is still functional.

    +

    C++ Server

    +

    The civetweb server is wrapped by our DebugServer class, which provides a public interface consisting of +a few methods invoked by the Filament engine.

    +

    Since each view corresponds to a frame graph, the engine should notify DebugServer of any changes to the views +on the engine side.

    +
      +
    • createView Notifies the debugger that a new view has been created.
      • +
    • updateView Notifies the debugger of updates to an existing view.
      • +
    • destroyView Notifies the debugger that a view is being removed.
      • +
    +

    JavaScript Client

    +

    The web app is built using LitElement, a lightweight library for creating Web Components. Our goal is to keep the code simple and modern, avoiding frameworks like React or Angular.

    +

    The app presents a view over a pseudo-database, which is essentially a global variable holding a dictionary that maps frame graph ids to objects following the JSON structure described below.

    +

    HTTP requests

    +

    The server responds to the following GET requests by returning a JSON blob. The {id} in these +requests is a concept specific to fgviewer (not Filament) which is an 8-digit hex string for identifying frame graphs.

    +
    +

    /api/framegraphs

    +

    Returns an array containing all framegraphs in an app. Example:

    +
    [{
+    "fgid": "00000000",
+    "viewName": "Main View",
+    "passes": [{
+        "name": "shadow pass",
+        "reads": [],
+        "writes": ["0"]
+    }],
+    "resources": [{
+        "id": "0",
+        "name": "shadowmap",
+        "properties": [{"resolution": "256x256"}, {"is_subresource": "false"}]
+    }]
+},
+{
+    "fgid": "00000001",
+    "viewName": "UI view",
+    ...
+}]
+
    +
    +

    /api/framegraph?fg={id}

    +

    Returns a specific framegraph info. Example:

    +
    {
+  "fgid": "00000000",
+  "viewName": "Main View",
+  "passes": [{
+    "name": "shadow pass",
+    "reads": [],
+    "writes": ["0"]
+  }],
+  "resources": [{
+    "id": "0",
+    "name": "shadowmap",
+    "properties": [{"resolution": "256x256"}, {"is_subresource": "false"}]
+  }]
+}
+
    +
    +

    /api/status

    +

    Returns one of the below:

    +
      +
    • 0: first time connected
      • +
    • 1: no-op
      • +
    • {fgid}: the corresponding frame graph has an update +
        +
      • Then the web view can request for the actual info using the previous api
        • +
      +
      • +
    +

    If the request gets timeout, the web page show disconnected to the user.

    +
    +

    Wish List

    +
      +
    • Display the texture contents on the webview
      • +
    + +
    + + +
    +
    + + + +
    + + + + + + + + + + + + + + + + + + +
    + + diff --git a/docs/dup/filamat.html b/docs/dup/filamat.html index 9cea839cf5..6f0ef7f792 100644 --- a/docs/dup/filamat.html +++ b/docs/dup/filamat.html @@ -336,7 +336,7 @@ void material(inout MaterialInputs material) {