Skip to content

TESTING_test_apps.md

Latest commit

 

History

History
100 lines (74 loc) · 4.69 KB

TESTING_test_apps.md

File metadata and controls

100 lines (74 loc) · 4.69 KB

GFXReconstruct Test Apps

Adding a Test App

  1. Create a new folder in the test_apps directory. Name the directory the same name as your test app.
  2. Add your code to the new folder
  3. Create a new CMakeLists.txt file in the new directory that builds your test app. For examples
  4. Include the new folder in the CMakeLists.txt file in the test_apps directory

See the triangle test app for examples.

Test App Architecture

The gfxrecon::test::TestAppBase class is provided as a base class for test apps. This base class provides basic Vulkan initialization and a render loop. The TestAppBase provides to following overridable virtual functions:

  • void configure_instance_builder(InstanceBuilder&) - called before instance creation in order to modify the instance creation, e.g. add instance extensions
  • void configure_physical_device_selector(PhysicalDeviceSelector&) - called before physical device selection in order to modify device selection
  • void configure_device_builder(DeviceBuilder&, PhysicalDevice const&) - called before device creation in order to modify device creation, e.g. add device extensions
  • void configure_swapchain_builder(SwapchainBuilder&) - called before swapchain creation in order to modify swapchain creation
  • void setup() - called after the swapchain has been built, but before the render loop. Can be used to setup test app specific resources
  • bool frame(const int frame_num) - executes a single frame of the render loop. Returns true to continue the render loop, false to exit
  • void cleanup() -- called after the render loop has stopped. Can be used to cleanup test app specific resources

Only the frame function is required. All others are optional.

Test Launcher

The test-launcher is an executable which can be used to launch test apps.

gfxrecon-test-launcher - A launcher for GFXReconstruct test apps.

Usage:
  gfxrecon-test-launcher [-h | --help] <test_name>

Required arguments:
  <test_name>   Name of the test app to launch.
                Options are: 
                  acquired-image
                  host-image-copy
                  multisample-depth
                  pipeline-binaries
                  shader-objects
                  sparse-resources
                  triangle
                  external-memory-fd-export
                  external-memory-fd-import
                  wait-for-present
                  trigger-trimming
                  [...]

Use of the TestAppBase is required to add a test app to the test-launcher.

In order to add a test app to the test-launcher, make sure to modify test_launcher.cpp using the following approach making sure to replace <test-name> with the name of your test app:

  1. Add #include <<test-name>-app.h>
  2. Add "<test-name>" to kAppNames
  3. Add the following code to CreateTestApp(): 
    else if (app_name == "<test-name>")
{
    app = std::make_unique<gfxrecon::test_app::<test_name>::App>();
}

Finally, make sure to add your test app library to the GFXRECON_TEST_LAUNCHER_LINK_LIBRARIES list in the following CMakeLists files:

  • android/test/test_apps/launcher/CMakeLists.txt
  • test/test_apps/launcher/CMakeLists.txt

Building Test Apps

Test apps are built as part of the default build CMAKE build process. In order to stop test apps from building, set the GFXRECON_INCLUDE_TEST_APPS CMake variable to OFF, e.g. provide -DGFXRECON_INCLUDE_TEST_APPS=OFF in your cmake command line.

Test App Verification

To run the test apps and validate output against known good '.gfxr' files, build the project and then run the test script from within the 'test' install directory.

On Windows: The test app must not be run as administrator. If you receive an error that the ps1 script is not digitally signed, you will need to run 'Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine' to allow the script to run.

Operating System ./scripts/build.py Test Directory Test Script
Windows build/windows/x64/output/test run-tests.ps1
Linux build/linux/x64/output/test run-tests.sh
macOS build/darwin/universal/output/test run-tests_macos.sh

Run A Single Test App

The default of Test Script run-tests.sh runs whole test apps. It could also run a single test app by specifying the test name, e.g. run-tests.sh triangle.

It could also run the test app straightforwardly without the test script. However, many environment variables set in the test script are necessary for running a single test app. Plus, some paths of the environment variables might have to be modified to match your environment.