Add enablers to expose semi-public APIs for QtQuick3D

Follow the same patterns as for qpa and rhi. Semi-public APIs will be
put under the "namespace" ssg which is short for Spatial Scene Graph.

Taks-number: QTBUG-116570
Change-Id: I38887f129ec90e67f6a929a0d8ea5ea8b8c49ee8
Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>

5 files changed, 87 insertions, 10 deletions

diff --git a/cmake/QtFrameworkHelpers.cmake b/cmake/QtFrameworkHelpers.cmake
index 6d67bc4a11..513cebf57c 100644
--- a/cmake/QtFrameworkHelpers.cmake
+++ b/cmake/QtFrameworkHelpers.cmake
@@ -72,7 +72,7 @@ function(qt_copy_framework_headers target)
 
     set(options)
     set(oneValueArgs)
-    set(multiValueArgs PUBLIC PRIVATE QPA RHI)
+    set(multiValueArgs PUBLIC PRIVATE QPA RHI SSG)
     cmake_parse_arguments(arg "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
 
     qt_internal_get_framework_info(fw ${target})
@@ -81,10 +81,11 @@ function(qt_copy_framework_headers target)
     set(output_dir_PRIVATE "${output_dir}/${fw_private_module_header_dir}/private")
     set(output_dir_QPA "${output_dir}/${fw_private_module_header_dir}/qpa")
     set(output_dir_RHI "${output_dir}/${fw_private_module_header_dir}/rhi")
+    set(output_dir_SSG "${output_dir}/${fw_private_module_header_dir}/ssg")
 
 
     set(out_files)
-    foreach(type IN ITEMS PUBLIC PRIVATE QPA RHI)
+    foreach(type IN ITEMS PUBLIC PRIVATE QPA RHI SSG)
         set(fw_output_header_dir "${output_dir_${type}}")
         foreach(hdr IN LISTS arg_${type})
             get_filename_component(in_file_path ${hdr} ABSOLUTE)
diff --git a/cmake/QtModuleHelpers.cmake b/cmake/QtModuleHelpers.cmake
index 6f85384d5d..ce4386986d 100644
--- a/cmake/QtModuleHelpers.cmake
+++ b/cmake/QtModuleHelpers.cmake
@@ -31,6 +31,7 @@ macro(qt_internal_get_internal_add_module_keywords option_args single_args multi
         PRIVATE_HEADER_FILTERS
         QPA_HEADER_FILTERS
         RHI_HEADER_FILTERS
+        SSG_HEADER_FILTERS
         HEADER_SYNC_SOURCE_DIRECTORY
         ${__default_target_info_args}
     )
@@ -119,6 +120,10 @@ endfunction()
 #     The regular expressions that filter RHI header files out of target sources.
 #     The value must use the following format 'regex1|regex2|regex3'.
 #
+#   SSG_HEADER_FILTERS
+#     The regular expressions that filter ssg header files out of target sources.
+#     The value must use the following format 'regex1|regex2|regex3'.
+#
 #   HEADER_SYNC_SOURCE_DIRECTORY
 #     The source directory for header sync procedure. Header files outside this directory will be
 #     ignored by syncqt. The specifying this directory allows to skip the parsing of the whole
@@ -458,6 +463,13 @@ function(qt_internal_add_module target)
         set_target_properties(${target}
             PROPERTIES _qt_module_rhi_headers_filter_regex "${rhi_filter_regex}")
 
+        set(ssg_filter_regex "")
+        if(arg_SSG_HEADER_FILTERS)
+            set(ssg_filter_regex "${arg_SSG_HEADER_FILTERS}")
+        endif()
+        set_target_properties(${target}
+            PROPERTIES _qt_module_ssg_headers_filter_regex "${ssg_filter_regex}")
+
         set(private_filter_regex ".+_p(ch)?\\.h")
         if(arg_PRIVATE_HEADER_FILTERS)
             set(private_filter_regex "${private_filter_regex}|${arg_PRIVATE_HEADER_FILTERS}")
@@ -905,6 +917,7 @@ function(qt_finalize_module target)
         PRIVATE ${module_headers_private}
         QPA ${module_headers_qpa}
         RHI ${module_headers_rhi}
+        SSG ${module_headers_ssg}
     )
 
     qt_finalize_framework_headers_copy(${target})
@@ -938,6 +951,7 @@ endfunction()
 #  * foo_private_include_dir with the value "QtCore/6.2.0/QtCore/private"
 #  * foo_qpa_include_dir with the value "QtCore/6.2.0/QtCore/qpa"
 #  * foo_rhi_include_dir with the value "QtCore/6.2.0/QtCore/rhi"
+#  * foo_ssg_include_dir with the value "QtQuick3D/6.2.0/QtQuick3D/ssg"
 #  * foo_interface_name the interface name of the module stored in _qt_module_interface_name
 #    property, e.g. Core.
 #
@@ -963,6 +977,9 @@ endfunction()
 #  * foo_<build|install>_rhi_include_dir with
 #    qtbase_build_dir/include/QtCore/6.2.0/QtCore/rhi for build interface and
 #    include/QtCore/6.2.0/QtCore/rhi for install interface.
+#  * foo_<build|install>_ssg_include_dir with
+#    qtbase_build_dir/include/<module>/x.y.z/<module>/ssg for build interface and
+#    include/<module>/x.y.z/<module>/ssg for install interface.
 # The following values are set by the function and might be useful in caller's scope:
 #  * repo_install_interface_include_dir contains path to the top-level repository include directory,
 #    e.g. qtbase_build_dir/include
@@ -999,6 +1016,8 @@ the different base name for the module info variables.")
         "${${result}_versioned_inner_include_dir}/qpa")
     set("${result}_rhi_include_dir"
         "${${result}_versioned_inner_include_dir}/rhi")
+    set("${result}_ssg_include_dir"
+        "${${result}_versioned_inner_include_dir}/ssg")
 
     # Module build interface directories
     set(repo_build_interface_include_dir "${QT_BUILD_DIR}/include")
@@ -1014,6 +1033,8 @@ the different base name for the module info variables.")
         "${repo_build_interface_include_dir}/${${result}_qpa_include_dir}")
     set("${result}_build_interface_rhi_include_dir"
         "${repo_build_interface_include_dir}/${${result}_rhi_include_dir}")
+    set("${result}_build_interface_ssg_include_dir"
+        "${repo_build_interface_include_dir}/${${result}_ssg_include_dir}")
 
     # Module install interface directories
     set(repo_install_interface_include_dir "${INSTALL_INCLUDEDIR}")
@@ -1029,6 +1050,8 @@ the different base name for the module info variables.")
         "${repo_install_interface_include_dir}/${${result}_qpa_include_dir}")
     set("${result}_install_interface_rhi_include_dir"
         "${repo_install_interface_include_dir}/${${result}_rhi_include_dir}")
+    set("${result}_install_interface_ssg_include_dir"
+        "${repo_install_interface_include_dir}/${${result}_ssg_include_dir}")
 
     set("${result}" "${module}" PARENT_SCOPE)
     set("${result}_versioned" "${module_versioned}" PARENT_SCOPE)
@@ -1043,6 +1066,7 @@ the different base name for the module info variables.")
     set("${result}_private_include_dir" "${${result}_private_include_dir}" PARENT_SCOPE)
     set("${result}_qpa_include_dir" "${${result}_qpa_include_dir}" PARENT_SCOPE)
     set("${result}_rhi_include_dir" "${${result}_rhi_include_dir}" PARENT_SCOPE)
+    set("${result}_ssg_include_dir" "${${result}_ssg_include_dir}" PARENT_SCOPE)
     set("${result}_interface_name" "${module_interface_name}" PARENT_SCOPE)
 
     # Setting module build interface directories in parent scope
@@ -1059,6 +1083,8 @@ the different base name for the module info variables.")
         "${${result}_build_interface_qpa_include_dir}" PARENT_SCOPE)
     set("${result}_build_interface_rhi_include_dir"
         "${${result}_build_interface_rhi_include_dir}" PARENT_SCOPE)
+    set("${result}_build_interface_ssg_include_dir"
+        "${${result}_build_interface_ssg_include_dir}" PARENT_SCOPE)
 
     # Setting module install interface directories in parent scope
     set(repo_install_interface_include_dir "${repo_install_interface_include_dir}" PARENT_SCOPE)
@@ -1074,6 +1100,8 @@ the different base name for the module info variables.")
         "${${result}_install_interface_qpa_include_dir}" PARENT_SCOPE)
     set("${result}_install_interface_rhi_include_dir"
         "${${result}_install_interface_rhi_include_dir}" PARENT_SCOPE)
+    set("${result}_install_interface_ssg_include_dir"
+        "${${result}_install_interface_ssg_include_dir}" PARENT_SCOPE)
 endfunction()
 
 function(qt_internal_list_to_json_array out_var list_var)
@@ -1181,7 +1209,7 @@ endfunction()
 function(qt_internal_install_module_headers target)
     set(options)
     set(one_value_args)
-    set(multi_value_args PUBLIC PRIVATE QPA RHI)
+    set(multi_value_args PUBLIC PRIVATE QPA RHI SSG)
     cmake_parse_arguments(arg "${options}" "${one_value_args}" "${multi_value_args}" ${ARGN})
 
     qt_internal_module_info(module ${target})
@@ -1207,6 +1235,7 @@ function(qt_internal_install_module_headers target)
             PRIVATE ${arg_PRIVATE}
             QPA ${arg_QPA}
             RHI ${arg_RHI}
+            SSG ${arg_ssg}
         )
     else()
         if(arg_PUBLIC)
@@ -1223,6 +1252,9 @@ function(qt_internal_install_module_headers target)
         if(arg_RHI)
             qt_install(FILES ${arg_RHI} DESTINATION "${module_install_interface_rhi_include_dir}")
         endif()
+        if(arg_SSG)
+            qt_install(FILES ${arg_SSG} DESTINATION "${module_install_interface_ssg_include_dir}")
+        endif()
     endif()
 endfunction()
 
@@ -1231,6 +1263,7 @@ function(qt_internal_collect_module_headers out_var target)
     set(${out_var}_private "")
     set(${out_var}_qpa "")
     set(${out_var}_rhi "")
+    set(${out_var}_ssg "")
     set(${out_var}_all "")
 
     qt_internal_get_target_sources(sources ${target})
@@ -1252,6 +1285,7 @@ function(qt_internal_collect_module_headers out_var target)
     get_target_property(private_filter ${target} _qt_module_private_headers_filter_regex)
     get_target_property(qpa_filter ${target} _qt_module_qpa_headers_filter_regex)
     get_target_property(rhi_filter ${target} _qt_module_rhi_headers_filter_regex)
+    get_target_property(ssg_filter ${target} _qt_module_ssg_headers_filter_regex)
 
     set(condition_independent_headers_warning "")
     foreach(file_path IN LISTS sources)
@@ -1305,6 +1339,8 @@ function(qt_internal_collect_module_headers out_var target)
             list(APPEND ${out_var}_qpa "${file_path}")
         elseif(rhi_filter AND file_name MATCHES "${rhi_filter}")
             list(APPEND ${out_var}_rhi "${file_path}")
+        elseif(ssg_filter AND file_name MATCHES "${ssg_filter}")
+            list(APPEND ${out_var}_ssg "${file_path}")
         elseif(private_filter AND file_name MATCHES "${private_filter}")
             list(APPEND ${out_var}_private "${file_path}")
         elseif((NOT public_filter OR file_name MATCHES "${public_filter}")
@@ -1328,7 +1364,7 @@ function(qt_internal_collect_module_headers out_var target)
     endif()
 
 
-    set(header_types public private qpa rhi)
+    set(header_types public private qpa rhi ssg)
     set(has_header_types_properties "")
     foreach(header_type IN LISTS header_types)
         get_target_property(current_propety_value ${target} _qt_module_has_${header_type}_headers)
@@ -1351,5 +1387,6 @@ function(qt_internal_collect_module_headers out_var target)
             _qt_module_has_private_headers
             _qt_module_has_qpa_headers
             _qt_module_has_rhi_headers
+            _qt_module_has_ssg_headers
     )
 endfunction()
diff --git a/cmake/QtQmakeHelpers.cmake b/cmake/QtQmakeHelpers.cmake
index 89284b0990..39e9dc816d 100644
--- a/cmake/QtQmakeHelpers.cmake
+++ b/cmake/QtQmakeHelpers.cmake
@@ -212,6 +212,7 @@ function(qt_get_qmake_module_name result module)
     string(REGEX REPLACE "Private$" "_private" module "${module}")
     string(REGEX REPLACE "Qpa$" "_qpa_lib_private" module "${module}")
     string(REGEX REPLACE "Rhi$" "_rhi_lib_private" module "${module}")
+    string(REGEX REPLACE "Ssg$" "_ssg_lib_private" module "${module}")
     string(TOLOWER "${module}" module)
     set(${result} ${module} PARENT_SCOPE)
 endfunction()
diff --git a/cmake/QtSyncQtHelpers.cmake b/cmake/QtSyncQtHelpers.cmake
index 4dba8fccfe..ee9a23610e 100644
--- a/cmake/QtSyncQtHelpers.cmake
+++ b/cmake/QtSyncQtHelpers.cmake
@@ -80,6 +80,7 @@ function(qt_internal_target_sync_headers target module_headers module_headers_ge
 
     get_target_property(qpa_filter_regex ${target} _qt_module_qpa_headers_filter_regex)
     get_target_property(rhi_filter_regex ${target} _qt_module_rhi_headers_filter_regex)
+    get_target_property(ssg_filter_regex ${target} _qt_module_ssg_headers_filter_regex)
     get_target_property(private_filter_regex ${target} _qt_module_private_headers_filter_regex)
 
     # We need to use the real paths since otherwise it may lead to the invalid work of the
@@ -103,6 +104,12 @@ function(qt_internal_target_sync_headers target module_headers module_headers_ge
         )
     endif()
 
+    if(ssg_filter_regex)
+        set(ssg_filter_argument
+            -ssgHeadersFilter "${ssg_filter_regex}"
+        )
+    endif()
+
     set(common_syncqt_arguments
         -module "${module}"
         -sourceDir "${source_dir_real}"
@@ -112,9 +119,11 @@ function(qt_internal_target_sync_headers target module_headers module_headers_ge
         -privateIncludeDir "${module_build_interface_private_include_dir}"
         -qpaIncludeDir "${module_build_interface_qpa_include_dir}"
         -rhiIncludeDir "${module_build_interface_rhi_include_dir}"
+        -ssgIncludeDir "${module_build_interface_ssg_include_dir}"
         -generatedHeaders ${module_headers_generated}
         ${qpa_filter_argument}
         ${rhi_filter_argument}
+        ${ssg_filter_argument}
         ${public_namespaces_filter}
         ${non_qt_module_argument}
         ${internal_module_argument}
diff --git a/src/tools/syncqt/main.cpp b/src/tools/syncqt/main.cpp
index 8d6709f981..f2a0f65fb0 100644
--- a/src/tools/syncqt/main.cpp
+++ b/src/tools/syncqt/main.cpp
@@ -179,6 +179,8 @@ public:
 
     const std::string &rhiIncludeDir() const { return m_rhiIncludeDir; }
 
+    const std::string &ssgIncludeDir() const { return m_ssgIncludeDir; }
+
     const std::string &stagingDir() const { return m_stagingDir; }
 
     const std::string &versionScriptFile() const { return m_versionScriptFile; }
@@ -189,6 +191,8 @@ public:
 
     const std::regex &rhiHeadersRegex() const { return m_rhiHeadersRegex; }
 
+    const std::regex &ssgHeadersRegex() const { return m_ssgHeadersRegex; }
+
     const std::regex &privateHeadersRegex() const { return m_privateHeadersRegex; }
 
     const std::regex &publicNamespaceRegex() const { return m_publicNamespaceRegex; }
@@ -220,7 +224,7 @@ public:
     void printHelp() const
     {
         std::cout << "Usage: syncqt -sourceDir <dir> -binaryDir <dir> -module <module name>"
-                     " -includeDir <dir> -privateIncludeDir <dir> -qpaIncludeDir <dir> -rhiIncludeDir <dir>"
+                     " -includeDir <dir> -privateIncludeDir <dir> -qpaIncludeDir <dir> -rhiIncludeDir <dir> -ssgIncludeDir <dir>"
                      " -stagingDir <dir> <-headers <header list>|-all> [-debug]"
                      " [-versionScript <path>] [-qpaHeadersFilter <regex>] [-rhiHeadersFilter <regex>]"
                      " [-framework [-frameworkIncludeDir <dir>]]"
@@ -246,6 +250,8 @@ public:
                      "                                  generated QPA header files.\n"
                      "  -rhiIncludeDir                  Module include directory for the \n"
                      "                                  generated RHI header files.\n"
+                     "  -ssgIncludeDir                  Module include directory for the \n"
+                     "                                  generated SSG header files.\n"
                      "  -stagingDir                     Temporary staging directory to collect\n"
                      "                                  artifacts that need to be installed.\n"
                      "  -knownModules                   list of known modules. syncqt uses the\n"
@@ -261,6 +267,8 @@ public:
                      "                                  the list of 'headers'.\n"
                      "  -rhiHeadersFilter               Regex that filters rhi header files from.\n"
                      "                                  the list of 'headers'.\n"
+                     "  -ssgHeadersFilter               Regex that filters ssg files from.\n"
+                     "                                  the list of 'headers'.\n"
                      "  -publicNamespaceFilter          Symbols that are in the specified\n"
                      "                                  namespace.\n"
                      "                                  are treated as public symbols.\n"
@@ -299,6 +307,7 @@ private:
     {
         std::string qpaHeadersFilter;
         std::string rhiHeadersFilter;
+        std::string ssgHeadersFilter;
         std::string privateHeadersFilter;
         std::string publicNamespaceFilter;
         static std::unordered_map<std::string, CommandLineOption<std::string>> stringArgumentMap = {
@@ -308,10 +317,12 @@ private:
             { "-privateHeadersFilter", { &privateHeadersFilter, true } },
             { "-qpaHeadersFilter", { &qpaHeadersFilter, true } },
             { "-rhiHeadersFilter", { &rhiHeadersFilter, true } },
+            { "-ssgHeadersFilter", { &ssgHeadersFilter, true } },
             { "-includeDir", { &m_includeDir } },
             { "-privateIncludeDir", { &m_privateIncludeDir } },
             { "-qpaIncludeDir", { &m_qpaIncludeDir } },
             { "-rhiIncludeDir", { &m_rhiIncludeDir } },
+            { "-ssgIncludeDir", { &m_ssgIncludeDir } },
             { "-stagingDir", { &m_stagingDir, true } },
             { "-versionScript", { &m_versionScriptFile, true } },
             { "-frameworkIncludeDir", { &m_frameworkIncludeDir, true } },
@@ -428,6 +439,9 @@ private:
         if (!rhiHeadersFilter.empty())
             m_rhiHeadersRegex = std::regex(rhiHeadersFilter);
 
+        if (!ssgHeadersFilter.empty())
+            m_ssgHeadersRegex = std::regex(ssgHeadersFilter);
+
         if (!privateHeadersFilter.empty())
             m_privateHeadersRegex = std::regex(privateHeadersFilter);
 
@@ -478,6 +492,7 @@ private:
     std::string m_privateIncludeDir;
     std::string m_qpaIncludeDir;
     std::string m_rhiIncludeDir;
+    std::string m_ssgIncludeDir;
     std::string m_stagingDir;
     std::string m_versionScriptFile;
     std::string m_frameworkIncludeDir;
@@ -496,6 +511,7 @@ private:
     bool m_warningsAreErrors = false;
     std::regex m_qpaHeadersRegex;
     std::regex m_rhiHeadersRegex;
+    std::regex m_ssgHeadersRegex;
     std::regex m_privateHeadersRegex;
     std::regex m_publicNamespaceRegex;
 
@@ -567,7 +583,7 @@ class SyncScanner
     size_t m_currentFileLineNumber = 0;
     bool m_currentFileInSourceDir = false;
 
-    enum FileType { PublicHeader = 0, PrivateHeader = 1, QpaHeader = 2, ExportHeader = 4, RhiHeader = 8 };
+    enum FileType { PublicHeader = 0, PrivateHeader = 1, QpaHeader = 2, ExportHeader = 4, RhiHeader = 8, SsgHeader = 16 };
     unsigned int m_currentFileType = PublicHeader;
 
     int m_criticalChecks = CriticalChecks;
@@ -787,6 +803,9 @@ public:
         if (isHeaderRhi(m_currentFilename))
             m_currentFileType = RhiHeader | PrivateHeader;
 
+        if (isHeaderSsg(m_currentFilename))
+            m_currentFileType = SsgHeader | PrivateHeader;
+
         if (std::regex_match(m_currentFilename, ExportsHeaderRegex))
             m_currentFileType |= ExportHeader;
     }
@@ -825,6 +844,7 @@ public:
         bool isPrivate = m_currentFileType & PrivateHeader;
         bool isQpa = m_currentFileType & QpaHeader;
         bool isRhi = m_currentFileType & RhiHeader;
+        bool isSsg = m_currentFileType & SsgHeader;
         bool isExport = m_currentFileType & ExportHeader;
         scannerDebug()
             << "processHeader:start: " << headerFile
@@ -832,6 +852,7 @@ public:
             << " isPrivate: " << isPrivate
             << " isQpa: " << isQpa
             << " isRhi: " << isRhi
+            << " isSsg: " << isSsg
             << std::endl;
 
         // Chose the directory where to generate the header aliases or to copy header file if
@@ -841,6 +862,8 @@ public:
             outputDir = m_commandLineArgs->qpaIncludeDir();
         else if (isRhi)
             outputDir = m_commandLineArgs->rhiIncludeDir();
+        else if (isSsg)
+            outputDir = m_commandLineArgs->ssgIncludeDir();
         else if (isPrivate)
             outputDir = m_commandLineArgs->privateIncludeDir();
 
@@ -899,7 +922,7 @@ public:
             unsigned int skipChecks = m_commandLineArgs->scanAllMode() ? AllChecks : NoChecks;
 
             // Collect checks that should skipped for the header file.
-            if (m_commandLineArgs->isNonQtModule() || is3rdParty || isQpa || isRhi
+            if (m_commandLineArgs->isNonQtModule() || is3rdParty || isQpa || isRhi || isSsg
                 || !m_currentFileInSourceDir || isGenerated) {
                 skipChecks = AllChecks;
             } else {
@@ -920,7 +943,7 @@ public:
 
             ParsingResult parsingResult;
             parsingResult.masterInclude = m_currentFileInSourceDir && !isExport && !is3rdParty
-                    && !isQpa && !isRhi && !isPrivate && !isGenerated;
+                    && !isQpa && !isRhi && !isSsg && !isPrivate && !isGenerated;
             if (!parseHeader(headerFile, parsingResult, skipChecks)) {
                 scannerDebug() << "parseHeader failed: " << headerFile << std::endl;
                 return false;
@@ -937,7 +960,7 @@ public:
             // Add the '#if QT_CONFIG(<feature>)' check for header files that supposed to be
             // included into the module master header only if corresponding feature is enabled.
             bool willBeInModuleMasterHeader = false;
-            if (!isQpa && !isRhi && !isPrivate) {
+            if (!isQpa && !isRhi && !isSsg && !isPrivate) {
                 if (m_currentFilename.find('_') == std::string::npos
                     && parsingResult.masterInclude) {
                     m_masterHeaderContents[m_currentFilename] = parsingResult.requireConfig;
@@ -1230,7 +1253,8 @@ public:
             ++linesProcessed;
 
             bool skipSymbols =
-                    (m_currentFileType & PrivateHeader) || (m_currentFileType & QpaHeader) || (m_currentFileType & RhiHeader);
+                    (m_currentFileType & PrivateHeader) || (m_currentFileType & QpaHeader) || (m_currentFileType & RhiHeader)
+                    || (m_currentFileType & SsgHeader);
 
             // Parse pragmas
             if (std::regex_match(buffer, MacroRegex)) {
@@ -1416,6 +1440,11 @@ public:
         return std::regex_match(headerFileName, m_commandLineArgs->rhiHeadersRegex());
     }
 
+    [[nodiscard]] bool isHeaderSsg(const std::string &headerFileName)
+    {
+        return std::regex_match(headerFileName, m_commandLineArgs->ssgHeadersRegex());
+    }
+
     [[nodiscard]] bool isHeaderPrivate(const std::string &headerFile)
     {
         return std::regex_match(headerFile, m_commandLineArgs->privateHeadersRegex());