OpenGL and OpenGL ES 2.0/3.X Conformance Test Contribution Guide

This document describes how to add new tests to the OpenGL and OpenGL ES 2.0/3.X conformance test suites.


Tips for developing new tests

In general all new test cases should be written in the new framework residing in the framework directory. Those tests should be added to the external/openglcts/modules directory in the appropriate place.

See instructions below.

Test framework overview

Tests are organized as a conceptual tree consisting of groups and, as leaves of the tree, atomic test cases. Each node in the hierarchy has three major functions that are called from test executor (tcu::TestExecutor):

  1. init() - called when executor enters test node
  2. iterate() - called for test cases until iterate() returns STOP
  3. deinit() - called when leaving node

Each node can access a shared test context (tcu::TestContext). The test context provides for example logging and resource access functionality. Test case results are also passed to executor using the test context (setTestResult()).

The root nodes are called test packages: They provide some package-specific behavior for the TestExecutor, and often provide package-specific context for test cases. CTS packages (except CTS-Configs.*) create a rendering context in init() and tear it down in deinit(). The rendering context is passed down in hierarchy in a package-specific glcts::Context object.

Test groups do not contain any test code. They usually create child nodes in init(). Default deinit() for group nodes will destroy any created child nodes, thus saving memory during execution.

Some test groups use a pre-defined list of children, while some may populate the list dynamically, parsing the test script.

Data Files

Data files are copied from source directory to build directory as a post-build step for glcts target. Compiled binaries read data files from <workdir>/gl_cts directory (for example: <workdir>/gl_cts/data/gles3/arrays.test).

The data file copy step means that glcts target must be built in order to see changes made to the data files in the source directories. On Linux this means invoking make in <builddir>.

The data files can be included in the built binaries. See section on build configuration for details. Android build always builds a complete APK package with all the required files.

Adding tests to dEQP Framework

Tests can be added to new or existing source files in external/openglcts/modules directory. To register a test case into the hierarchy, the test case must be added as a child in a test group that is already connected to the hierarchy.

There is a mini shader test framework (glcts::ShaderLibrary) that can create shader cases from *.test files. See file es3cTestPackage.cpp for details on, how to add new *.test files, and the existing test files in external/openglcts/modules/gles3 for format reference.

Adding tests to GTF

This module is essentially frozen and should no longer be extended.

Coding conventions

The OpenGL CTS source is formatted using clang-format v4.0. Before submitting your changes make sure that the changes are formatted properly. A recommended way to do that is to run script on the changes, e.g.:

cd external/openglcts && git diff -U0 HEAD^ . | python  -style=file -i -p3 -binary clang-format-4.0

Submitting changes

Please refer to the Pull Requests section of the Open GL CTS Public Wiki.