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