Document new build_apps options in 1.10.13

rdb · rdb · commit 8c419d0e1949 · 2022-12-06T20:58:31.000+01:00
diff --git a/distribution/building-binaries.rst b/distribution/building-binaries.rst
@@ -176,11 +176,14 @@ combination is:
    * - p3fmod_audio
      - Audio (including 3D audio) support using FMOD (note the licensing!)
    * - pandaegg
-     - Enables support for reading .egg files (usually not necessary)
+     - Enables support for reading .egg files. Generally, you should not include
+       this, since .egg files are automatically converted to .bam during build.
    * - p3ptloader
-     - Adds support for additional model formats beyond BAM
+     - Adds support for additional model formats. You probably want to instead
+       add those model extensions to the ``bam-model-extensions`` list.
    * - p3assimp
-     - Adds support for additional model formats beyond BAM by using Assimp
+     - Adds support for additional model formats. You probably want to instead
+       add those model extensions to the ``bam-model-extensions`` list.
 
 Note that some plug-ins use third-party libraries that may have different
 licensing terms from Panda3D. More information about these libraries can be
@@ -228,8 +231,13 @@ platform tags to increase these versions:
      - Set this to target the oldest 32-bit Linux distributions.
    * - manylinux2010_x86_64
      - Target 64-bit Linux distributions more recent than (more or less) 2010.
+       No longer supported by Python 3.11, which uses manylinux2014_x86_64.
    * - manylinux2010_i686
      - Target 32-bit Linux distributions more recent than (more or less) 2010.
+   * - manylinux2014_x86_64
+     - Target 64-bit Linux distributions more recent than (more or less) 2014.
+   * - manylinux2014_i686
+     - Target 32-bit Linux distributions more recent than (more or less) 2014.
    * - macosx_10_9_x86_64
      - Target Intel Macs running OS X Mavericks or higher. Recommended.
    * - macosx_10_6_x86_64
diff --git a/distribution/list-of-build-options.rst b/distribution/list-of-build-options.rst
@@ -89,3 +89,20 @@ file_handlers
    User-defined file handlers for an extension override the default handler.
    By default, there is only one file handler registered: for .egg files, which
    runs egg2bam.
+
+bam_model_extensions
+   New in Panda3D 1.10.13. A list of model extensions that are automatically
+   converted to .bam during build. Add extensions to this if you are using other
+   file formats than .egg (such as .gltf and .glb for
+   :ref:`glTF files <gltf-files>`).
+
+strip_docstrings
+   New in Panda3D 1.10.13. If true, which is the default, all docstrings will be
+   removed as an optimization, and any use of ``__doc__`` will return ``None``.
+   Set this to false if you need to keep these docstrings for some reason.
+
+prefer_discrete_gpu
+   New in Panda3D 1.10.13. On systems with both an integrated and dedicated
+   GPUs, tells the driver that the application prefers to use the dedicated GPU,
+   which usually provides higher performance. At the moment, this option is only
+   implemented on Windows, and only for NVIDIA and AMD graphics cards.
diff --git a/optimization/performance-issues/motherboard-integrated-video.rst b/optimization/performance-issues/motherboard-integrated-video.rst
@@ -30,3 +30,51 @@ The following code can be used to determine which GPU is in use:
 
       std::cerr << win->get_gsg()->get_driver_vendor() << "\n"
                 << win->get_gsg()->get_driver_renderer() << "\n";
+
+Forcing Use of Discrete GPU on Windows
+--------------------------------------
+
+On Windows, it is possible to force the NVIDIA and AMD graphics drivers to
+automatically select the high-peformance dedicated graphics card, by compiling
+special symbols into the main executable.
+
+.. only:: python
+
+   While developing, the main executable is ``python.exe``, which does not set
+   these symbols. But when :ref:`building an application <distribution>`,
+   build_apps can automatically add these special symbols. Simply add this
+   option to the build_apps options block in setup.py:
+
+   .. code-block:: python
+
+      'prefer_discrete_gpu': True,
+
+   This option is available as of Panda3D 1.10.13.
+
+.. only:: cpp
+
+   Simply copy-paste the following symbols into the source file containing your
+   main entry point:
+
+   .. code-block:: cpp
+
+      #ifdef _WIN32
+      extern "C" {
+        __declspec(dllexport) DWORD AmdPowerXpressRequestHighPerformance = 0x00000001;
+        __declspec(dllexport) DWORD NvOptimusEnablement = 0x00000001;
+      }
+      #endif
+
+Forcing Use of Discrete GPU on Linux
+------------------------------------
+
+On Linux, some drivers can be told to use the discrete GPU by setting
+``DRI_PRIME=1`` in the environment. However, this is not considered reliable at
+this time, so it is not done by Panda3D automatically. It is suggested to
+document this as a possibility for your end-users or add an option for this
+setting that can be disabled.
+
+When distributing a .desktop file, it is also possible to add the following key
+to the file::
+
+   PrefersNonDefaultGPU=true
diff --git a/pipeline/gltf-files.rst b/pipeline/gltf-files.rst
@@ -131,6 +131,40 @@ the vertex shader:
 
    binormal = cross(p3d_Normal, p3d_Tangent.xyz) * p3d_Tangent.w
 
+Distributing glTF Models
+------------------------
+
+.. only:: python
+
+   When :ref:`building your application <distribution>`, the plug-ins
+   responsible for loading glTF models are not distributed along by default.
+   It is much better to convert the model to the optimized .bam format for this
+   purpose. As of Panda3D 1.10.13, this can be done automatically, by adding the
+   extensions to the ``bam_model_extensions`` list:
+
+   .. code-block:: python
+
+      options = {
+          'build_apps': {
+              ...
+              'include_patterns': [
+                  # Make sure the gltf/glb file is being found
+                  '**/*.gltf',
+                  '**/*.glb',
+                  '**/*.jpg',
+                  ...
+              ],
+              # Models with these extensions are converted to .bam automatically
+              'bam_model_extensions': ['.gltf', '.glb', '.egg'],
+              ...
+
+.. only:: cpp
+
+   To avoid having to include the plug-ins with a distributed application, use
+   the gltf2bam utility (provided with panda3d-gltf) or write a script to
+   convert the model to .bam using :meth:`.NodePath.write_bam_file()` and ship
+   the converted .bam file instead of the original source file.
+
 External Links
 --------------
 
diff --git a/pipeline/model-file-formats.rst b/pipeline/model-file-formats.rst
@@ -206,7 +206,8 @@ For several formats for which Panda3D ships with a to-egg conversion tool,
 Panda3D can automatically do the step of converting the model to .egg on load.
 For example, Panda3D ships with a flt2egg converter, which can convert
 OpenFlight models to the Egg format. If you try to load a .flt file, Panda3D
-will implicitly invoke flt2egg behind the scenes.
+will implicitly invoke flt2egg behind the scenes. The plug-in responsible for
+this is called p3ptloader.
 
 The formats supported by this plug-in are OpenFlight (.flt), LightWave (.lwo),
 AutoCAD (.dxf), VRML (.wrl), Direct X (.x), and Wavefront OBJ (.obj).
