external/openglcts/CONTRIBUTING.md

   1 OpenGL and OpenGL ES 2.0/3.X Conformance Test Contribution Guide
   2 =================
   3
   4 This document describes how to add new tests to the OpenGL and OpenGL ES
   5 2.0/3.X conformance test suites.
   6
   7 Contents
   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
  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.
  22
  23 See instructions below.
  24
  25 ### Test framework overview
  26
  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
  33
  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
  37 (`setTestResult()`).
  38
  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.
  44
  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.
  48
  49 Some test groups use a pre-defined list of children, while some may populate
  50 the list dynamically, parsing the test script.
  51
  52 ### Data Files
  53
  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`).
  58
  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>`.
  62
  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.
  66
  67 ### Adding tests to dEQP Framework
  68
  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.
  72
  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`
  76 for format reference.
  77
  78 ### Adding tests to GTF
  79
  80 This module is essentially frozen and should no longer be extended.
  81
  82 Coding conventions
  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.:
  88
  89         cd external/openglcts && git diff -U0 HEAD^ . | python clang-format-diff.py  -style=file -i -p3 -binary clang-format-4.0
  90
  91 Submitting changes
  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.