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