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