1OpenGL and OpenGL ES 2.0/3.X Conformance Test Contribution Guide 2================= 3 4This document describes how to add new tests to the OpenGL and OpenGL ES 52.0/3.X conformance test suites. 6 7Contents 8------------------------ 9- [Tips for developing new tests](#tips-for-developing-new-tests) 10 - [Test framework overview](#test-framework-overview) 11 - [Data Files](#data-files) 12 - [Adding tests to dEQP Framework](#adding-tests-to-deqp-framework) 13 - [Adding tests to GTF](#adding-tests-to-gtf) 14- [Coding conventions](#coding-conventions) 15- [Submitting changes](#submitting-changes) 16 17Tips for developing new tests 18------------------------ 19In general all new test cases should be written in the new framework residing 20in the `framework` directory. Those tests should be added to the 21`external/openglcts/modules` directory in the appropriate place. 22 23See instructions below. 24 25### Test framework overview 26 27Tests are organized as a conceptual tree consisting of groups and, as leaves of 28the tree, atomic test cases. Each node in the hierarchy has three major 29functions that are called from test executor (`tcu::TestExecutor`): 301. `init()` - called when executor enters test node 312. `iterate()` - called for test cases until `iterate()` returns `STOP` 323. `deinit()` - called when leaving node 33 34Each node can access a shared test context (`tcu::TestContext`). The test 35context provides for example logging and resource access functionality. 36Test case results are also passed to executor using the test context 37(`setTestResult()`). 38 39The root nodes are called test packages: They provide some package-specific 40behavior for the TestExecutor, and often provide package-specific context for 41test cases. CTS packages (except `CTS-Configs.*`) create a rendering context 42in `init()` and tear it down in `deinit()`. The rendering context is passed 43down in hierarchy in a package-specific `glcts::Context` object. 44 45Test groups do not contain any test code. They usually create child nodes in 46`init()`. Default `deinit()` for group nodes will destroy any created child 47nodes, thus saving memory during execution. 48 49Some test groups use a pre-defined list of children, while some may populate 50the list dynamically, parsing the test script. 51 52### Data Files 53 54Data files are copied from source directory to build directory as a post-build 55step for `glcts` target. Compiled binaries read data files 56from `<workdir>/gl_cts` directory 57(for example: `<workdir>/gl_cts/data/gles3/arrays.test`). 58 59The data file copy step means that `glcts` target must be built in order to see 60changes made to the data files in the source directories. On Linux this means 61invoking `make` in `<builddir>`. 62 63The data files can be included in the built binaries. See section on build 64configuration for details. Android build always builds a complete APK package 65with all the required files. 66 67### Adding tests to dEQP Framework 68 69Tests can be added to new or existing source files in `external/openglcts/modules` directory. 70To register a test case into the hierarchy, the test case must be added as a 71child in a test group that is already connected to the hierarchy. 72 73There is a mini shader test framework (`glcts::ShaderLibrary`) that can create 74shader cases from `*.test` files. See file `es3cTestPackage.cpp` for details on, 75how to add new `*.test` files, and the existing test files in `external/openglcts/modules/gles3` 76for format reference. 77 78### Adding tests to GTF 79 80This module is essentially frozen and should no longer be extended. 81 82Coding conventions 83------------------------ 84The OpenGL CTS source is formatted using [`clang-format` v4.0](http://clang.llvm.org/docs/ClangFormat.html). 85Before submitting your changes make sure that the changes are formatted properly. 86A recommended way to do that is to run [`clang-format-diff.py`](https://llvm.org/svn/llvm-project/cfe/trunk/tools/clang-format/clang-format-diff.py) 87script on the changes, e.g.: 88 89 cd external/openglcts && git diff -U0 HEAD^ . | python clang-format-diff.py -style=file -i -p3 -binary clang-format-4.0 90 91Submitting changes 92------------------------ 93Please refer to the [Pull Requests](https://github.com/KhronosGroup/Vulkan-CTS/wiki/Contributing#pull-requests) 94section of the Open GL CTS Public Wiki. 95