external/openglcts/README.md

   1 OpenGL and OpenGL ES 2.0/3.X Conformance Test Instructions
   2 =================
   3
   4 This document describes how to build, port, and run the OpenGL and OpenGL ES
   5 2.0/3.X conformance tests, and how to verify and submit test results.
   6
   7 The Conformance Tests are built on dEQP framework. dEQP documentation is
   8 available at http://source.android.com/devices/graphics/testing.html
   9
  10
  11 Contents
  12 ------------------------
  13  - [Test History](#test-history)
  14  - [Introduction](#introduction)
  15  - [Test Environment Requirements](#test-environment-requirements)
  16  - [Configuring and Building the Tests](#configuring-and-building-the-tests)
  17     - [Configuration](#configuration)
  18     - [Building the Tests](#building-the-tests)
  19        - [Windows](#windows)
  20        - [Linux](#linux)
  21        - [Android](#android)
  22  - [Porting](#porting)
  23     - [Common Porting Changes](#common-porting-changes)
  24     - [Other Allowable Porting Changes](#other-allowable-porting-changes)
  25  - [Running the Tests](#running-the-tests)
  26     - [Conformance runs](#conformance-runs)
  27        - [Linux and Windows](#linux-and-windows)
  28        - [Android](#android-1)
  29     - [Running Subsets](#running-subsets)
  30        - [Command line options](#command-line-options)
  31     - [Understanding the Results](#understanding-the-results)
  32     - [Test Logs](#test-logs)
  33  - [Debugging Test Failures](#debugging-test-failures)
  34  - [Waivers](#waivers)
  35  - [Creating a Submission Package](#creating-a-submission-package)
  36  - [Submission Update Package](#submission-update-package)
  37  - [Passing Criteria](#passing-criteria)
  38  - [Troubleshooting](#troubleshooting)
  39     - [Crashes early on in the run](#crashes-early-on-in-the-run)
  40     - [Build fails](#build-fails)
  41  - [Adding new tests](#adding-new-tests)
  42  - [Acknowledgments](#acknowledgments)
  43  - [Revision History](#revision-history)
  44
  45 Test History
  46 ------------------------
  47 The OpenGL and OpenGL ES Conformance Tests are expanded versions of the
  48 OpenGL ES 2.x Conformance Test. Much of the development was done by Symbio, Inc.
  49 under a contract with The Khronos Group. drawElements donated a considerable
  50 number of new tests and a new execution framework for version 1.1.
  51 The tests are built from the same source code base, although some individual
  52 feature tests are specific to OpenGL or OpenGL ES and their specification
  53 versions, and compilation options differing between OpenGL and OpenGL ES affect
  54 how the tests are compiled and executed in some cases.
  55
  56 Introduction
  57 ------------------------
  58
  59 This document contains instructions for certifying conformance of implementations
  60 of the OpenGL and OpenGL ES APIs. The steps of the process are as follows:
  61
  62 1. Configure the conformance tests and port them to your platform.
  63 2. Build a test executable and run it against your implementation to produce
  64 result logs.
  65 3. Debug any test failures and modify your implementation as needed until it
  66 passes the test.
  67 4. Create a Submission Package containing your final result logs and other
  68 documents describing the tested platform.
  69 5. Submit the results to the appropriate Review Committee via the
  70 Khronos Adopters web page. The Committee will examine your submission and will
  71 notify you within thirty days if they find any issues requiring action on your part.
  72
  73 This document describes each of these steps in detail. It also provides advice
  74 on reproducing, understanding, and debugging test failures, and discusses how
  75 to extend or modify the tests and the test framework.
  76
  77 The reader is assumed to be a fluent programmer experienced with command line
  78 utilities and build tools, such as CMake or Make.
  79
  80 Test Environment Requirements
  81 ------------------------
  82
  83 The conformance tests require a file system. The file system requires support
  84 for long file names (i.e. > 8.3 name format). Source files in the conformance
  85 tests use mixed case file names. When the `--verbose` option is used, rendered
  86 images and test case shaders are copied to the log files. This can lead to quite
  87 large log files, up to hundreds of megabytes on disk.
  88
  89 Each execution of the conformance test writes a text-format results log to a disk.
  90 You will need to include this log as part of your conformance submission package.
  91
  92 The conformance test executable can be large. Compiler options and CPU instruction
  93 sets can cause substantial variation. The disk space required for the build
  94 including all the temporary files can be up to 400MB.
  95
  96 The build environment is expected to support C++ with exceptions and
  97 the Standard Template Library (STL).
  98
  99 Configuring and Building the Tests
 100 ------------------------
 101 The CTS is built via CMake build system. The requirements for the build are as follows:
 102 - CMake 3.0 (3.6 for Android NDK r17+ builds) or newer
 103 - C++ compiler with STL and exceptions support
 104 - Unix: Make + GCC / Clang
 105 - Windows: Visual Studio or Windows SDK (available free-of-charge)
 106 - Android: Android SDK and NDK for host platform
 107
 108 The build is controlled by the file CMakeLists.txt found at the root of
 109 the CTS source.
 110
 111 If the platform and compiler tools you use are not supported, you may be able to
 112 add support for that platform and tools to the build system. If you do this,
 113 please submit your changes back to Khronos for inclusion in the official tests
 114 going forward.
 115
 116 Otherwise, if you choose not to use the supplied Makefiles, you must construct
 117 an equivalent build system for the chosen development environment(s).
 118
 119 ### Configuration
 120
 121 The build is configured by using `CMakeLists.txt` files in the build target
 122 directory (`targets/`).  They specify platform-specific configuration, including
 123 include paths and link libraries.
 124
 125 The main `CMakeLists.txt` includes the target file based on the `DEQP_TARGET`
 126 variable. For example `-DDEQP_TARGET=my_target` will use the target description
 127 file `targets/my_target/my_target.cmake`.
 128
 129 See the main `CMakeLists.txt` file for the description of the variables that
 130 the target file can set.
 131
 132 Porting to a new platform includes either creating a new target file, or
 133 modifying an existing target description.
 134
 135 **NOTE**: All paths, except `TCUTIL_PLATFORM_SRCS` are relative to root source
 136 directory. `TCUTIL_PLATFORM_SRCS` is relative to `framework/platform` directory.
 137
 138 Following target files are provided with the package:
 139
 140 | Name | Description  |
 141 |:---------|-----------------|
 142 |android | Used in Android build. Requires use of suitable toolchain file (see `cmake/` directory) |
 143 |default| Checks for presence of GL, ES2, ES3, and EGL libraries and headers in default search paths and configures build accordingly|
 144 |null | Null build target |
 145 |nullws | NullWS build target |
 146 |x11_egl| X11 build for platforms with native EGL support|
 147 |x11_glx| X11 build for platforms with native GLX support|
 148 |x11_egl_glx| X11 build for platforms with native EGL/GLX support|
 149
 150 **Example target file (targets/null/null.cmake):**
 151 ```
 152 message("*** Using null context target")
 153
 154 set(DEQP_TARGET_NAME "Null")
 155
 156 set(TCUTIL_PLATFORM_SRCS
 157         null/tcuNullPlatform.cpp
 158         null/tcuNullPlatform.hpp
 159         null/tcuNullRenderContext.cpp
 160         null/tcuNullRenderContext.hpp
 161         null/tcuNullContextFactory.cpp
 162         null/tcuNullContextFactory.hpp
 163         )
 164 ```
 165
 166 **Common configuration variables and their default values in CMake syntax:**
 167
 168 - Target name
 169 ```
 170 set(DEQP_TARGET_NAME "UNKNOWN")
 171 ```
 172
 173 - List of link libraries per API.  If no libraries are specified, entry points
 174 are loaded at run-time by default for OpenGL ES APIs. EGL always requires link
 175 libraries.  OpenGL always uses run-time loading.
 176 ```
 177 set(DEQP_GLES2_LIBRARIES   )
 178 set(DEQP_GLES3_LIBRARIES   )
 179 set(DEQP_GLES31_LIBRARIES  )
 180 set(DEQP_GLES32_LIBRARIES  )
 181 set(DEQP_EGL_LIBRARIES     )
 182 set(DEQP_OPENGL_LIBRARIES  )
 183 ```
 184
 185 - Generic platform libraries required to link a working OpenGL (ES) Application
 186 (e.g. X11 libraries on Unix/X11)
 187 ```
 188 set(DEQP_PLATFORM_LIBRARIES )
 189 ```
 190
 191 - Libraries / binaries that need to be copied to the build target dir
 192 ```
 193 set(DEQP_PLATFORM_COPY_LIBRARIES )
 194 ```
 195
 196 - If running on Linux using X11 for creating windows etc., enable this.
 197 ```
 198 set(DEQP_USE_X11 OFF)
 199 ```
 200
 201 - Embed the test files in the test Before building with this set (if GTF module is present), run these commands:
 202 ```
 203 cd external/kc-cts/src/GTF_ES/glsl/GTF
 204 perl mergeTestFilesToCSource.pl
 205 ```
 206
 207  In your target `.cmake` file add
 208 ```
 209 set(DEQP_EMBED_TESTS ON)
 210 add_definitions(-DHKEMBEDDEDFILESYSTEM)
 211 ```
 212
 213 ### Building the Tests
 214
 215 To build the framework, you need first to download sources for zlib, libpng, glslang,
 216 spirv-headers, and spirv-tools.
 217
 218 To download sources, run:
 219
 220         python external/fetch_sources.py
 221
 222 For OpenGL CTS releases, and OpenGL ES CTS releases prior to opengl-es-cts-3.2.4.0
 223 download Khronos Confidential Conformance Test Suite:
 224
 225         python external/fetch_kc_cts.py
 226
 227 For OpenGL CTS releases, and OpenGL ES CTS releases prior to opengl-es-cts-3.2.4.0
 228 the results for the tests included in this suite must be included in a
 229 conformance submission.
 230
 231 **NOTE**: You need to be a Khronos Adopter and have an active account
 232 at [Khronos Gitlab](https://gitlab.khronos.org/) to be able to download
 233 Khronos Confidential CTS.
 234 It is possible to run and build the CTS without the Khronos Confidential CTS.
 235 For OpenGL CTS releases, and OpenGL ES CTS releases prior to opengl-es-cts-3.2.4.0
 236 Khronos Confidential CTS is mandatory if you plan to make a
 237 conformance submission (see [Creating a Submission Package](#creating-a-submission-package)).
 238 For opengl-es-cts-3.2.4.0 and later OpenGL ES CTS releases Khronos Confidential CTS
 239 results must not be included in a submission package.
 240
 241
 242 With CMake out-of-source builds are always recommended. Create a build directory
 243 of your choosing, and in that directory generate Makefiles or IDE project
 244 using Cmake.
 245
 246 #### Windows
 247
 248 Requirements:
 249 - Visual Studio (2015 or newer recommended) or Windows SDK
 250 - CMake 3.10.2 Windows native version (i.e. not Cygwin version)
 251 - For GL/ES2/ES3.x tests: OpengGL, OpenGL ES 2 or ES 3.x libraries and headers
 252
 253 To choose the backend build system for CMake, choose one of the following Generator Names for the
 254 command line examples in the next steps:
 255 - VS2015: "Visual Studio 14"
 256 - NMake (must be run in VS or SDK command prompt): "NMake Makefiles"
 257
 258 Building GL, ES2, or ES3.x conformance tests:
 259
 260         cmake <path to openglcts> -DDEQP_TARGET=default -G"<Generator Name>"
 261         cmake --build .
 262
 263 Khronos Confidential CTS doesn't support run-time selection of API context.
 264 If you intend to run it you need to additionally supply `GLCTS_GTF_TARGET`
 265 option to you cmake command, e.g.:
 266
 267         cmake <path to openglcts> -DDEQP_TARGET=default -DGLCTS_GTF_TARGET=<target> -G"<Generator Name>"
 268
 269 Available `<target>`s are `gles2`, `gles3`, `gles31`, `gles32`, and `gl`.
 270 The default `<target>` is `gles32`.
 271
 272 It's also possible to build `GL-CTS.sln` in Visual Studio instead of running
 273 the `cmake --build .` command.
 274
 275 **NOTE**: Do not create the build directory under the source directory
 276 (i.e anywhere under `<path to openglcts>`) on Windows, since it causes
 277 random build failures when copying data files around.
 278
 279 **NOTE**: You can use the CMake for Windows GUI to do configuration and project
 280 file generation.
 281
 282 **NOTE**: If using cygwin, you must install and ensure you use the Windows
 283 version of cmake. The cygwin vesion does not contain the Visual Studio
 284 generators. Here is a shell function you can put in your cygwin `.bash_profile`
 285 to use it easily. With this you can simply type `wcmake` to run the Windows version.
 286
 287 ```
 288 function wcmake () {
 289     (TMP=$tmp TEMP=$temp; unset tmp; unset temp; "C:/Program Files (x86)/CMake 2.8/bin/cmake" "$@")
 290 }
 291 ```
 292
 293 #### Linux
 294
 295 Required tools:
 296 - Standard build utilities (make, gcc, etc.)
 297 - CMake 3.10.2
 298 - Necessary API libraries (OpenGL, GLES, EGL depending on configuration)
 299
 300 Building ES2 or ES3.x conformance tests:
 301
 302         cmake <path to openglcts> -DDEQP_TARGET=null -DGLCTS_GTF_TARGET=gles32
 303         cmake --build .
 304
 305 Building OpenGL conformance tests:
 306
 307         cmake <path to openglcts> -DDEQP_TARGET=null -DGLCTS_GTF_TARGET=gl
 308         cmake --build .
 309
 310 Khronos Confidential CTS doesn't support run-time selection of API context.
 311 If you intend to run it then the `GLCTS_GTF_TARGET` option is necessary.
 312
 313 Available values for `GLCTS_GTF_TARGET` are `gles2`, `gles3`, `gles31`, `gles32`, and `gl`.
 314 The default value is `gles32`.
 315
 316 CMake chooses to generate Makefiles by default. Other generators can be used
 317 as well. See CMake help for more details.
 318
 319 #### Android
 320
 321 The conformance tests come with native Android support. The following packages
 322 are needed in order to build an Android binary:
 323 - Python 3.x (for the build related scripts, some other scripts still use Python 2.7.x)
 324 - Android NDK r17c
 325 - Android SDK with API 28 packages and tools installed
 326 - Apache Ant
 327
 328 An Android binary (for ES 3.2) can be built using command:
 329
 330         python scripts/android/build_apk.py --target=openglcts --sdk <path to Android SDK> --ndk <path to Android NDK>
 331
 332 By default the CTS package will be built for the Android API level 28.
 333 Another API level may be supplied using --native-api command line option.
 334
 335 If Khronos Confidential CTS is present then the script will set `GLCTS_GTF_TARGET`
 336 to `gles32` by default.
 337 It is possible to specify a different `GLCTS_GTF_TARGET` target by invoking the script
 338 with the `--kc-cts-target` option, e.g.:
 339
 340         python scripts/android/build_apk.py --target=openglcts --kc-cts-target=gles31 --sdk <path to Android SDK> --ndk <path to Android NDK>
 341
 342 Available values for `--kc-cts-target` are `gles32`, `gles31`, `gles3`, `gles2` and `gl`.
 343
 344 The package can be installed by either running:
 345
 346         python scripts/android/install_apk.py --target=openglcts
 347
 348 By default the CTS package will contain libdeqp.so built for `armeabi-v7a`, `arm64-v8a`,
 349 `x86`, and `x86_64` ABIs, but that can be changed with `--abis` command line option.
 350
 351 To pick which ABI to use at install time, following commands must be used
 352 instead:
 353
 354         adb install -g --abi <ABI name> <build root>/Khronos-CTS.apk /data/local/tmp/Khronos-CTS.apk
 355
 356 Porting
 357 ------------------------
 358 The Conformance Tests have been designed to be relatively platform-, OS-, and
 359 compiler-independent. Adopters are responsible for final changes needed to allow
 360 the Test to run on the platform they wish to
 361 certify as conformant.
 362
 363 ### Common Porting Changes
 364
 365 Porting the dEQP framework requires implementation of either `glu::Platform` or,
 366 on platforms supporting EGL, the `tcu::EglPlatform` interface. The porting layer
 367 API is described in detail in following files:
 368
 369         framework/common/tcuPlatform.hpp
 370         framework/opengl/gluPlatform.hpp
 371         framework/egl/egluPlatform.hpp
 372         framework/platform/tcuMain.cpp
 373
 374 This version of the dEQP framework includes ports for Windows (both EGL and WGL),
 375 X11 (EGL and XGL), and Android.
 376
 377 Base portability libraries in `framework/delibs` seldom need changes. However,
 378 introducing support for a new compiler or a new processor family may require
 379 some changes to correctly detect and parameterize the environment.
 380
 381 Porting typically involves three types of changes:
 382 1. Changes to the make system used to generate the test executable.
 383 2. Changes needed to adapt the test executable to the operating system used on the platform.
 384 3. Changes to the platform specific GL and EGL header files.
 385
 386 Changes should normally be confined to build files (CMake or Python) or source
 387 files (.c, .h, .cpp, and .h files) in the following directories or their
 388 subdirectories:
 389 - `framework/platform`
 390 - `targets`
 391
 392 If you find that you must change other source (.c, .cpp, .h, or .hpp) files,
 393 you will need to file a waiver as described below.
 394
 395 Note that the conformance tests assume that the implementation supports EGL.
 396 However EGL is not required for OpenGL or OpenGL ES conformance.
 397
 398 Most of the tests require at least 256x256 pixels resolution in order to run properly
 399 and produce stable results. It is, therefore, important to ensure that a port to a
 400 new platform can support surfaces that fulfill width and height requirements.
 401
 402 ### Other Allowable Changes
 403
 404 Changes to fix bugs in the conformance test are allowed. A bug in the conformance
 405 test is a behavior which causes clearly incorrect execution (e.g., hanging, crashing,
 406 or memory corruption), OR which requires behavior which contradicts or exceeds
 407 the requirements of the relevant OpenGL or OpenGL ES Specification. Before
 408 being used for a submission, bugfixes must be accepted and merged into
 409 the CTS repository. `git cherry-pick` is strongly recommended as a method of
 410 applying bug fixes.
 411
 412 Other changes must be accompanied by a [waiver](#waivers).
 413
 414 NOTE: When cherry-picking patches on top of release tag, please use `git cherry-pick -x`
 415 to include original commit hash in the commit message.
 416
 417 Running the Tests
 418 ------------------------
 419 All the following commands need to be run in the CTS build directory. If you
 420 need to move the binaries from the build directory, remember to copy the
 421 data directories named `gl_cts`, `gles2`, `gles3`, and `gles31` and its subdirectories
 422 from the build directory to the test target in the same relative locations.
 423
 424 If the build instructions have been followed as-is, the correct path is:
 425
 426         cd <builddir>/external/openglcts/modules
 427
 428 ### Conformance runs
 429 A conformance run can be launched either by running the `cts-runner` binary with
 430 appropriate options on Linux/Windows or by running an Android application.
 431
 432 ### Linux and Windows
 433 Conformance run for OpenGL ES 3.2 on Windows:
 434
 435         Debug/cts-runner.exe --type=es32
 436           [For ES 3.1 use --type=es31; ES 3.0 use --type=es3; for ES 2.0, use --type=es2]
 437
 438 Conformance run for OpenGL 3.0 - 4.6 on Windows:
 439
 440         Debug/cts-runner.exe --type=glxy
 441           [x and y are the major and minor specifiction versions]
 442
 443 Full list of parameters for the `cts-runner` binary:
 444 ```
 445 --type=[esN[M]|glNM] Conformance test run type. Choose from
 446                                          ES: es2, es3, es31, es32
 447                                          GL: gl30, gl31, gl32, gl33, gl40, gl41, gl42, gl43, gl44, gl45, gl46
 448 --waivers=[path]     Path to xml file containing waived tests
 449 --logdir=[path]      Destination directory for log files
 450 --summary            Print summary without running the tests
 451 --verbose            Print out and log more information
 452 ```
 453
 454 The conformance run will create one or more `.qpa` files per tested config, a
 455 summary `.qpa` file containing run results and a summary `.xml` file containing
 456 command line options for each run, all of which should be included in your
 457 conformance submission package. The final verdict will be printed out at
 458 the end of run.
 459
 460 Sometimes it is useful to know the command line options used for the conformance
 461 before the run completed. Full conformance run configuration is written
 462 to `cts-run-summary.xml` and this file can be generated by adding `--summary`
 463 parameter.
 464
 465 By default the `cts-runner` does not include result images or shaders used in
 466 the logs. Adding parameter `--verbose` will cause them to be included in
 467 the logs. Images will be embedded as PNG data into the`.qpa` log files.
 468 See Section [Test Logs](#test-logs) for instructions on how to view the images.
 469
 470 To direct logs to a directory, add `--logdir=[path]` parameter.
 471
 472 To specify waived tests, add `--waivers=[path]` parameter.
 473
 474 **NOTE**: Due to the lack of support for run-time selection of API context in the
 475 Khronos Confidential CTS, a conformance run may fail if it is executed for an API
 476 version that doesn't match the `GLCTS_GTF_TARGET` value used during the build step.
 477
 478 #### Android
 479
 480 Once the CTS binary is built and installed on the device, a new application
 481 called `ES3.2 CTS`, `ES3.1 CTS`, `ES3 CTS`, `ES2 CTS`, `GL4.5 CTS`, or `GL4.6 CTS`
 482 (depending on the test version you built) should appear in the launcher.
 483 Conformance test runs can be done by launching the applications.
 484
 485 Alternatively it is possible to start a conformance run from the command line,
 486 for example to launch a GLES 3.2 conformance run use:
 487
 488         am start -n org.khronos.gl_cts/org.khronos.cts.ES32Activity -e logdir "/sdcard/logs"
 489
 490 For GLES 2.0, GLES 3.0, GLES 3.1, GL 4.5, or GL 4.6 conformance runs, substitute
 491 the following activity name (respectively) ES2Activity, ES3Activity, ES31Activity,
 492 GL45Activity, or GL46Activity.
 493
 494 Test logs will be written to `/sdcard` by default. The log path can be
 495 customized by supplying a `logdir` string extra in launch intent. Verbose mode
 496 can be enabled by supplying a `verbose` = `"true"` string extra. See
 497 the following example:
 498
 499         am start -n org.khronos.gl_cts/org.khronos.cts.ES32Activity -e logdir "/sdcard/logs" -e verbose "true"
 500
 501 Conformance run configuration can be generated by supplying a `summary` = `"true"`
 502 string extra. See the following example:
 503
 504         am start -n org.khronos.gl_cts/org.khronos.cts.ES32Activity -e logdir "/sdcard/logs" -e summary "true"
 505
 506 Waivers can be specified by supplying a `waivers` string extra. See the following example:
 507
 508         am start -n org.khronos.gl_cts/org.khronos.cts.ES32Activity -e logdir "/sdcard/logs" -e waivers "/sdcard/waivers.xml"
 509
 510 **NOTE**: Supplying a `summary` = `"true"` string extra will result in the `cts-run-summary.xml` file
 511 being written out but no tests will be executed.
 512
 513 Individual tests can be launched as well by targeting
 514 `org.khronos.gl_cts/android.app.NativeActivity` activity. Command line
 515 arguments must be supplied in a `cmdLine` string extra. See following example:
 516
 517         am start -n org.khronos.gl_cts/android.app.NativeActivity -e cmdLine "cts --deqp-case=KHR-GLES32.info.version --deqp-gl-config-id=1 --deqp-log-filename=/sdcard/ES32-egl-config-1.qpa --deqp-surface-width=128 --deqp-surface-height=128"
 518
 519 In addition to the detailed `*.qpa` output files, the Android port of the CTS
 520 logs a summary of the test run, including the pass/fail status of each test.
 521 This summary can be viewed using the Android *logcat* utility.
 522
 523 See Section [Running Subsets](#running-subsets) below for details on command
 524 line parameters.
 525
 526 ### Running Subsets
 527
 528 Run shader compiler loop test cases from the OpenGL ES 3.0 CTS using EGL config with ID 3:
 529
 530         Debug/glcts.exe --deqp-case=KHR-GLES3.shaders.loops.* --deqp-gl-config-id=3
 531
 532 Note that the GL context version is determined by the case name. `KHR-GLES3` in
 533 the example above selects OpenGL ES 3.0. The command to run the same test
 534 against OpenGL version 4.1 is:
 535
 536         Debug/glcts.exe --deqp-case=GL41-CTS.shaders.loops.* --deqp-gl-config-id=3
 537
 538 To list available test cases (writes out `*-cases.txt` files per module), run:
 539
 540         Debug/glcts.exe --deqp-runmode=txt-caselist
 541
 542 The type of the run for cts-runner chooses a specific list of test cases to
 543 be run. The selected tests can be checked from the summary logs. To run
 544 the same tests, just give equivalent test selection parameters to the `glcts`.
 545
 546 #### Command line options
 547
 548 Full list of parameters for the `glcts` binary:
 549 ```
 550   -h, --help
 551     Show this help
 552
 553   -n, --deqp-case=<value>
 554     Test case(s) to run, supports wildcards (e.g. dEQP-GLES2.info.*)
 555
 556   --deqp-caselist=<value>
 557     Case list to run in trie format (e.g. {dEQP-GLES2{info{version,renderer}}})
 558
 559   --deqp-caselist-file=<value>
 560     Read case list (in trie format) from given file
 561
 562   --deqp-caselist-resource=<value>
 563     Read case list (in trie format) from given file located application's assets
 564
 565   --deqp-stdin-caselist
 566     Read case list (in trie format) from stdin
 567
 568   --deqp-log-filename=<value>
 569     Write test results to given file
 570     default: 'TestResults.qpa'
 571
 572   --deqp-runmode=[execute|xml-caselist|txt-caselist|stdout-caselist]
 573     Execute tests, or write list of test cases into a file
 574     default: 'execute'
 575
 576   --deqp-caselist-export-file=<value>
 577     Set the target file name pattern for caselist export
 578     default: '${packageName}-cases.${typeExtension}'
 579
 580   --deqp-watchdog=[enable|disable]
 581     Enable test watchdog
 582     default: 'disable'
 583
 584   --deqp-crashhandler=[enable|disable]
 585     Enable crash handling
 586     default: 'disable'
 587
 588   --deqp-base-seed=<value>
 589     Base seed for test cases that use randomization
 590     default: '0'
 591
 592   --deqp-test-iteration-count=<value>
 593     Iteration count for cases that support variable number of iterations
 594     default: '0'
 595
 596   --deqp-visibility=[windowed|fullscreen|hidden]
 597     Default test window visibility
 598     default: 'windowed'
 599
 600   --deqp-surface-width=<value>
 601     Use given surface width if possible
 602     default: '-1'
 603
 604   --deqp-surface-height=<value>
 605     Use given surface height if possible
 606     default: '-1'
 607
 608   --deqp-surface-type=[window|pixmap|pbuffer|fbo]
 609     Use given surface type
 610     default: 'window'
 611
 612   --deqp-screen-rotation=[unspecified|0|90|180|270]
 613     Screen rotation for platforms that support it
 614     default: '0'
 615
 616   --deqp-gl-context-type=<value>
 617     OpenGL context type for platforms that support multiple
 618
 619   --deqp-gl-config-id=<value>
 620     OpenGL (ES) render config ID (EGL config id on EGL platforms)
 621     default: '-1'
 622
 623   --deqp-gl-config-name=<value>
 624     Symbolic OpenGL (ES) render config name
 625
 626   --deqp-gl-context-flags=<value>
 627     OpenGL context flags (comma-separated, supports debug and robust)
 628
 629   --deqp-cl-platform-id=<value>
 630     Execute tests on given OpenCL platform (IDs start from 1)
 631     default: '1'
 632
 633   --deqp-cl-device-ids=<value>
 634     Execute tests on given CL devices (comma-separated, IDs start from 1)
 635     default: ''
 636
 637   --deqp-cl-build-options=<value>
 638     Extra build options for OpenCL compiler
 639
 640   --deqp-egl-display-type=<value>
 641     EGL native display type
 642
 643   --deqp-egl-window-type=<value>
 644     EGL native window type
 645
 646   --deqp-egl-pixmap-type=<value>
 647     EGL native pixmap type
 648
 649   --deqp-log-images=[enable|disable]
 650     Enable or disable logging of result images
 651     default: 'enable'
 652
 653   --deqp-log-shader-sources=[enable|disable]
 654     Enable or disable logging of shader sources
 655     default: 'enable'
 656
 657   --deqp-test-oom=[enable|disable]
 658     Run tests that exhaust memory on purpose
 659     default: 'enable'
 660
 661   --deqp-archive-dir=<value>
 662     Path to test resource files
 663     default: '.'
 664
 665   --deqp-log-flush=[enable|disable]
 666     Enable or disable log file fflush
 667     default: 'enable'
 668
 669
 670   --deqp-renderdoc=[enable|disable]
 671     Enable RenderDoc frame markers
 672     default: 'disable'
 673
 674   --deqp-fraction=<value>
 675     Run a fraction of the test cases (e.g. N,M means run group%M==N)
 676     default: ''
 677
 678   --deqp-fraction-mandatory-caselist-file=<value>
 679     Case list file that must be run for each fraction
 680     default: ''
 681
 682   --deqp-waiver-file=<value>
 683     Read waived tests from given file
 684     default: ''
 685
 686   --deqp-runner-type=[any|none|amber]
 687     Filter test cases based on runner
 688     default: 'any'
 689
 690   --deqp-terminate-on-fail=[enable|disable]
 691     Terminate the run on first failure
 692     default: 'disable'
 693
 694   --deqp-egl-config-id=<value>
 695     Legacy name for --deqp-gl-config-id
 696     default: '-1'
 697
 698   --deqp-egl-config-name=<value>
 699     Legacy name for --deqp-gl-config-name
 700
 701   --deqp-waiver-file=<value>
 702     Path to xml file containing waived tests
 703 ```
 704
 705 ### Understanding the Results
 706
 707 At the end of a completed test run, a file called `cts-run-summary.xml` is
 708 generated. It will contain summaries per configuration and the full command
 709 lines for the `glcts` application
 710 (See Section [Running Subsets](#running-subsets)) for debugging purposes.
 711 Additionally, a summary string similar to one below is printed:
 712 ```
 713 4/4 sessions passed, conformance test PASSED
 714 ```
 715
 716 If the run fails, the message will say `FAILED` instead of `PASSED`. Under
 717 Linux or Windows, this string is printed to stdout if available. Under Android,
 718 it is emitted to the Android logging system for access via *logcat*.
 719
 720 Each test case will be logged into the `.qpa` files in XML. Below is a minimal
 721 example of a test case log. The Result element contains the final verdict in
 722 the `StatusCode` attribute. Passing cases will have `Pass` and failing cases
 723 `Fail`. Other results such as `QualityWarning`, `CompatibilityWarning`,
 724 `NotSupported` or `ResourceError` are possible. Only `Fail` status will count
 725 as failure for conformance purposes.
 726 ```
 727 <TestCaseResult Version="0.3.2" CasePath="ES2-CTS.info.vendor" CaseType="SelfValidate">
 728     <Text>Vendor A</Text>
 729     <Result StatusCode="Pass">Pass</Result>
 730 </TestCaseResult>
 731 ```
 732
 733 If the failure count is zero for all config sequences, the implementation
 734 passes the test. Note that in addition to a successful test result,
 735 a Submission Package must satisfy the conditions specified below under
 736 [Passing Criteria](#passing-criteria) in order to achieve conformance certification.
 737
 738 ### Test Logs
 739
 740 The CTS writes test logs in XML encapsulated in a simple plain-text container
 741 format. Each tested configuration listed in `cts-run-summary.xml`
 742
 743 To analyse and process the log files, run the following scripts
 744 - `verify_submission.py` located in [VK-GL-CTS-Tools](https://github.com/KhronosGroup/VK-GL-CTS-Tools): Script that verifies logs based on `cts-run-summary.xml` file.
 745 - `scripts/log/log_to_csv.py`: This utility converts `.qpa` log into CSV format. This is
 746 useful for importing results into other systems.
 747 - `scripts/log/log_to_xml.py`: Converts `.qpa` into well-formed XML document. The document
 748 can be then viewed in browser using the testlog.{xsl,css} files.
 749
 750 Some browsers, like Chrome, limit local file access. In such case, the files
 751 must be accessed over HTTP. Python comes with a simple HTTP server suitable
 752 for the purpose. Run `python -m SimpleHTTPServer` in the directory containing
 753 the generated XML files and point the browser to `127.0.0.1:8000`.
 754
 755 Parser for the `.qpa` log file format in python is provided in
 756 `scripts/log/log_parser.py`.
 757
 758 Python scripts require python 2.7 or newer in 2.x series. They are not
 759 compatible with python 3.x.
 760
 761 Debugging Test Failures
 762 ------------------------
 763 The best first step is to run the failing test cases via `glcts` executable to
 764 get the more verbose logs. Use, for example, the `log_to_xml.py` script
 765 detailed in Section [Test Logs](#test-logs), to view the generated logs.
 766 If the visual inspection of the logs does not give sufficient hints on the
 767 nature of the issue, inspecting the test code and stepping through it in
 768 debugger should help.
 769
 770 Waivers
 771 ------------------------
 772 The procedure for requesting a waiver is to report the issue by filing a bug
 773 report in the Gitlab VK GL CTS project
 774 (https://gitlab.khronos.org/Tracker/vk-gl-cts). When you create your submission
 775 package, include references to the waivers as described in the adopters' agreement.
 776 [Fully-qualified links](https://en.wikipedia.org/wiki/Fully_qualified_domain_name)
 777 to bug reports are highly recommended.
 778 Including as much information as possible in your bug report will ensure the issue
 779 can be progressed as speedily as possible. Such bug report must
 780 include a link to suggested file changes. Issues must be labeled `Waiver` and `OpenGL-ES`
 781 (for OpenGL ES submissions) or `Waiver` and `OpenGL` (for OpenGL submissions) and
 782 identify the CTS release tag and affected tests.
 783
 784 Creating a Submission Package
 785 ------------------------
 786 Please see the [Creating a Submission Package page](https://github.com/KhronosGroup/VK-GL-CTS/wiki/Creating-a-OpenGL-and-OpenGL-ES-Submission-Package).
 787
 788 Submission Update Package
 789 ------------------------
 790 Please see the [Submission Update Package page](https://github.com/KhronosGroup/VK-GL-CTS/wiki/Submission-Update-Package).
 791
 792 Passing Criteria
 793 ------------------------
 794 Please see the [Conformance Submission Passing Criteria page](https://github.com/KhronosGroup/VK-GL-CTS/wiki/OpenGL-and-OpenGL-ES-Conformance-Submission-Passing-Criteria).
 795
 796 Troubleshooting
 797 ------------------------
 798 ### Crashes early on in the run
 799 If using run-time entry point loading, it is possible that not all required
 800 entry points are available. This will result in `NULL` pointer dereferencing.
 801
 802 ### Build fails
 803 First try re-running the build. If that does not help and you have used the
 804 same build directory with different version of the CTS, remove the build
 805 directory and run the CMake again.
 806
 807 Adding new tests
 808 ------------------------
 809
 810 See the [Contribution Guide](CONTRIBUTING.md)
 811
 812 Acknowledgments
 813 ------------------------
 814 The Khronos Group gratefully acknowledges the support of drawElements Oy,
 815 who donated a large number of GLSL tests and a new test framework and build system.
 816
 817 The Khronos Group also gratefully acknowledges the support of 3DLabs Inc.,
 818 who gave permission to use the 3DLabs Graphics Test Framework (GTF).
 819
 820 The first internal version of the test was created by Bruno Schwander of
 821 Hooked Wireless, under a development contract with the Khronos Group.
 822
 823 Symbio added tests specific to OpenGL and OpenGL ES 3.0.
 824
 825 drawElements added their donated language tests and build system.
 826
 827 The CTS results from these efforts, together with additional hard work by
 828 volunteers from the OpenGL ES Working Group, the OpenGL ARB Working Group,
 829 and their member companies, including:
 830
 831 - Sumit Agarwal, Imagination Technologies
 832 - Eric Anholt, Intel
 833 - Oleksiy Avramchenko, Sony
 834 - Anthony Berent, ARM
 835 - Joseph Blankenship, AMD
 836 - Jeff Bolz, NVIDIA
 837 - Pierre Boudier, AMD
 838 - Benji Bowman, Imagination Technologies
 839 - Pat Brown, NVIDIA
 840 - David Cairns, Apple
 841 - Mark Callow, ArtSpark
 842 - Antoine Chauveau, NVIDIA
 843 - Aske Simon Christensen, ARM
 844 - Lin Chen, Qualcomm
 845 - Mathieu Comeau, QNX
 846 - Graham Connor, Imagination Technologies
 847 - Slawomir Cygan, Intel
 848 - Piotr Czubak, Intel
 849 - Piers Daniell, NVIDIA
 850 - Matthias Dejaegher, ZiiLabs
 851 - Chris Dodd, NVIDIA
 852 - David Donohoe, Movidius
 853 - Alex Eddy, Apple
 854 - Sean Ellis, ARM
 855 - Bryan Eyler, NVIDIA
 856 - Erik Faye-Lund, ARM
 857 - Nicholas FitzRoy-Dale, Broadcom
 858 - Michael Frydrych, NVIDIA
 859 - Toshiki Fujimori, Takumi
 860 - David Garcia, Qualcomm
 861 - Frido Garritsen, Vivante
 862 - Klaus Gerlicher, NVIDIA
 863 - Slawomir Grajewski, Intel
 864 - Jonas Gustavsson, Sony
 865 - Nick Haemel, NVIDIA
 866 - Matthew Harrison, Imagination Technologies
 867 - Pyry Haulos, drawElements
 868 - Jim Hauxwell, Broadcom
 869 - Valtteri Heikkil, Symbio
 870 - Tsachi Herman, AMD
 871 - Mathias Heyer, NVIDIA
 872 - Atsuko Hirose, Fujitsu
 873 - Ari Hirvonen, NVIDIA
 874 - Rune Holm, ARM
 875 - Jaakko Huovinen, Nokia
 876 - James Jones, Imagination Technologies
 877 - Norbert Juffa, NVIDIA
 878 - Jordan Justen, Intel
 879 - Sandeep Kakarlapudi, ARM
 880 - Anssi Kalliolahti, NVIDIA
 881 - Philip Kamenarsky, NVIDIA
 882 - Krzysztof Kaminski, Intel
 883 - Daniel Kartch, NVIDIA
 884 - Maxim Kazakov, DMP
 885 - Jon Kennedy, 3DLabs
 886 - John Kessenich
 887 - Daniel Koch, NVIDIA
 888 - Benjamin Kohler-Crowe, NVIDIA
 889 - Georg Kolling, Imagination Technologies
 890 - Misa Komuro, DMP
 891 - Boguslaw Kowalik, Intel
 892 - Aleksandra Krstic, Qualcomm
 893 - Karol Kurach, NVIDIA
 894 - VP Kutti
 895 - Sami Kyostila, Google
 896 - Teemu Laakso, Symbio
 897 - Antoine Labour, Sony
 898 - Alexandre Laurent, Imagination Technologies
 899 - Jon Leech, Khronos
 900 - Graeme Leese, Broadcom
 901 - I-Gene Leong, Intel
 902 - Radoslava Leseva, Imagination Technologies
 903 - Jake Lever, NVIDIA
 904 - Fred Liao, MediaTek
 905 - Bill Licea-Kane, Qualcomm
 906 - Benj Lipchak, Apple
 907 - Wayne Lister, Imagination Technologies
 908 - Isaac Liu, NVIDIA
 909 - Weiwan Liu, NVIDIA
 910 - Zhifang Long, Marvell
 911 - Toni L&#246;nnberg, AMD
 912 - Erik Lovlie
 913 - Christer Lunde, ARM
 914 - Zong-Hong Lyu, DMP
 915 - Daniel Mahashin, NVIDIA
 916 - Rob Matthesen, NVIDIA
 917 - Tom McReynolds, NVIDIA (CTS TSG Chair, ES 1.1)
 918 - Bruce Merry, ARM
 919 - Assif Mirza, Imagination Technologies
 920 - Zhenyao Mo, Google
 921 - Kazuhiro Mochizuki, Fujitsu
 922 - Affie Munshi, Apple
 923 - Yeshwant Muthusamy, Samsung
 924 - Mirela Nicolescu, Broadcom
 925 - Glenn Nissen, Broadcom
 926 - Michael O'Hara, AMD
 927 - Eisaku Ohbuchi, DMP
 928 - Tom Olson, ARM
 929 - Tapani Palli, Intel
 930 - Brian Paul, VMWare
 931 - Remi Pedersen, ARM
 932 - Adrian Peirson, ARM
 933 - Russell Pflughaupt, NVIDIA
 934 - Anuj Phogat, Intel
 935 - Tero Pihlajakoski, Nokia
 936 - Peter Pipkorn, NVIDIA
 937 - Acorn Pooley, NVIDIA
 938 - Guillaume Portier, ArtSpark
 939 - Greg Prisament, Lychee Software
 940 - Jonathan Putsman, Imagination Technologies
 941 - Mike Quinlan, AMD
 942 - Tarik Rahman, CodePlay
 943 - Kalle Raita, drawElements
 944 - Daniel Rakos, AMD
 945 - Manjunatha Ramachandra
 946 - John Recker, NVIDIA
 947 - Maurice Ribble, Qualcomm (CTS TSG Chair, ES 2.0)
 948 - James Riordon, Khronos
 949 - Lane Roberts, Samsung
 950 - Ian Romanick, Intel
 951 - Greg Roth, NVIDIA
 952 - Kenneth Russell, Google
 953 - Matteo Salardi, Imagination Technologies
 954 - Jeremy Sandmel, Apple
 955 - Shusaku Sawato, DMP
 956 - Chris Scholtes, Fujitsu
 957 - Mathias Schott, NVIDIA
 958 - Bruno Schwander, Hooked Wireless
 959 - Graham Sellers, AMD
 960 - Shereef Shehata, Texas Instruments
 961 - Benjamin Shen, Vivante
 962 - Robert Simpson, Qualcomm
 963 - Stuart Smith, Imagination Technologies
 964 - Janusz Sobczak, Mobica
 965 - Jacob Strom, Ericsson
 966 - Timo Suoranta, Broadcom
 967 - Jan Svarovsky, Ideaworks3D
 968 - Anthony Tai, Apple
 969 - Payal Talati, Imagination Technologies
 970 - Gregg Tavares, Google
 971 - Ross Thompson, NVIDIA
 972 - Jeremy Thorne, Broadcom
 973 - Jani Tikkanen, Symbio
 974 - Antti Tirronen, Qualcomm (CTS TSG Chair, ES 3.0/3.1)
 975 - Robert Tray, NVIDIA
 976 - Matt Turner, Intel
 977 - Eben Upton, Broadcom
 978 - Jani Vaarala, Nokia
 979 - Dmitriy Vasilev, NVIDIA
 980 - Chad Versace, Intel
 981 - Holger Waechtler, Broadcom
 982 - Joerg Wagner, ARM
 983 - Jun Wang, Imagination Technologies
 984 - Yuan Wang, Imagination Technologies
 985 - Hans-Martin Will
 986 - Ewa Wisniewska, Mobica
 987 - Dominik Witczak, Mobica
 988 - Oliver Wohlmuth, Fujitsu
 989 - Yanjun Zhang, Vivante
 990 - Lefan Zhong, Vivante
 991 - Jill Zhou
 992 - Marek Zylak, NVIDIA
 993 - Iliyan Dinev, Imagination Technologies
 994 - James Glanville, Imagination Technologies
 995 - Mark Adams, NVIDIA
 996 - Alexander Galazin, ARM
 997 - Riccardo Capra, ARM
 998 - Lars-Ivar Simonsen, ARM
 999 - Fei Yang, ARM
1000
1001 Revision History
1002 ------------------------
1003 - 0.0 - Tom Olson
1004
1005   Initial version cloned from `ES2_Readme`, plus feedback from Mark Callow.
1006
1007 - 0.2 - Tom Olson
1008
1009   Modified to incorporate feedback in bug 8534.
1010
1011 - 0.3 - Jon Leech
1012
1013   Added details for OpenGL Conformance.
1014
1015 - 0.4 - Jon Leech 2012/10/31
1016
1017   Add configuration & build section, and table of contents
1018
1019 - 0.5 - Jon Leech 2012/10/31
1020
1021   Fix typos noted by Mark Callow in bug 8534.
1022
1023 - 0.6 - Jon Leech 2012/11/13
1024
1025   Discuss automatic version selection and document support for OpenGL 3.3-4.3.
1026
1027 - 0.7 - Jon Leech 2012/11/14
1028
1029   Minor cleanup for GL version numbers per Bug 8534 comment #41.
1030
1031 - 0.8 - Tom Olson 2013/1/25
1032
1033   Updated GL status in preparation for ES 3.0 release, removed display
1034   parameters from product description, and removed mention of sample submission.
1035
1036 - 0.9 - Jon Leech 2013/07/17
1037
1038   Restore GL-specific details in preparation for initial GL CTS release.
1039
1040 - 1.0 - Jon Leech 2013/07/17
1041
1042   Change references to Visual Studio 11 to Visual Studio 2012 per bug 9862.
1043   Reset change tracking to reduce clutter.
1044
1045 - 1.1 - Kalle Raita 2013/10/30
1046
1047   Updated documentation after the integration of the drawElements framework and
1048   language tests.
1049
1050 - 1.2 - Kalle Raita 2013/12/03
1051
1052   Removed TODOs, added some notes on further development, and notes on file
1053   dependencies. Exact list of directory sub-trees that can be modified during porting.
1054
1055 - 1.3 - Tom Olson 2014/05/27
1056
1057   Updates for ES CTS 3.1.1.0 . Added Passing Criteria, updated examples to
1058   include 3.1 versioning, and updated Acknowledgements.
1059
1060 - 1.4 - Alexander Galazin 2016/05/12
1061
1062   Updates for ES CTS 3.2.1.0.
1063
1064 - 2.0 - Alexander Galazin 2016/09/23
1065
1066   Moved the contents to README.md.
1067   Updated to reflect new CTS structure and build instructions.
1068
1069 - 2.1 - Alexander Galazin 2016/12/15
1070
1071   Updates in preparation for the new release.
1072   Document restructuring, more detailed process of creating a submission package.
1073   Incorporated OpenGL/CTS issue 39 and 40 in the Passing Criteria.