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