| OLD | NEW |
|---|
| (Empty) |
| 1 Runtime Configuration | |
| 2 ===================== | |
| 3 | |
| 4 Skia supports the configuration of various aspects of its behavior at runtime, | |
| 5 allowing developers to enable\/disable features, or to experiment with numerical | |
| 6 quantities without recompiling. | |
| 7 | |
| 8 ## Enabling runtime configuration | |
| 9 | |
| 10 In order to use a runtime-configurable variable in your source, simply: | |
| 11 | |
| 12 <!--?prettify?--> | |
| 13 ~~~~ | |
| 14 #include "SkRTConf.h" | |
| 15 ~~~~ | |
| 16 | |
| 17 ## Declaring a runtime-configurable variable | |
| 18 | |
| 19 At file scope, declare your variable like so: | |
| 20 | |
| 21 <!--?prettify?--> | |
| 22 ~~~~ | |
| 23 SK_CONF_DECLARE( confType, varName, confName, defaultValue, description ); | |
| 24 ~~~~ | |
| 25 | |
| 26 For example, to declare a boolean variable called ` c_printShaders ` that can be | |
| 27 changed at runtime, you would do something like | |
| 28 | |
| 29 <!--?prettify?--> | |
| 30 ~~~~ | |
| 31 SK_CONF_DECLARE( bool, c_printShaders, "gpu.printShaders", false, "print the | |
| 32 source code of any internally generated GPU shaders" ); | |
| 33 ~~~~ | |
| 34 | |
| 35 It is safe to declare variables this way in header files; the variables will be | |
| 36 declared as static, but since they are read\-only\-ish \(they can be changed | |
| 37 through a special mechanism; see below\), this is safe. | |
| 38 | |
| 39 ## Using a runtime-configurable variable | |
| 40 | |
| 41 The variables created by `SK_CONF_DECLARE` can be used in normal C\+\+ code as | |
| 42 if they were regular contant variables. For example: | |
| 43 | |
| 44 <!--?prettify?--> | |
| 45 ~~~~ | |
| 46 if (c_printShaders) { | |
| 47 // actually print out the shaders | |
| 48 } | |
| 49 ~~~~ | |
| 50 | |
| 51 ## Changing a runtime-configurable variable after launch | |
| 52 | |
| 53 If, for some reason, you want to change the value of a runtime-configurable | |
| 54 variable after your program has started, you can do this with the `SK_CONF_SET` | |
| 55 macro: | |
| 56 | |
| 57 <!--?prettify?--> | |
| 58 ~~~~ | |
| 59 SK_CONF_SET( "gpu.printShaders", false ) | |
| 60 ~~~~ | |
| 61 | |
| 62 Note that we're using the `confName` parameter to the declaration, not | |
| 63 `varName`. This is because this configuration option may appear in multiple | |
| 64 files \(especially if you declared it in a header!\), and we need to make sure | |
| 65 to update all variables' values, not just the one that's locally visible to the | |
| 66 file you are currently in. | |
| 67 | |
| 68 ## Changing a runtime-configurable variable before launch | |
| 69 | |
| 70 This is the primary intended use of these variables. There are two ways that you | |
| 71 can control the values of runtime-configurable variables at launch time: a | |
| 72 skia.conf configuration file, or through the use of environment variables. | |
| 73 | |
| 74 ### Using skia.conf | |
| 75 | |
| 76 The skia.conf file is a simple line-based configuration file containing | |
| 77 key-value pairs. It supports python-style \# comments. For our example, we might | |
| 78 see a configuration file that looks like: | |
| 79 | |
| 80 <!--?prettify?--> | |
| 81 ~~~~ | |
| 82 gpu.printShaders true | |
| 83 gpu.somethingElse 3.14159 | |
| 84 matrix.invertProperly false # math is hard | |
| 85 ... | |
| 86 ~~~~ | |
| 87 | |
| 88 *Note: boolean values may be set as 1, 0, true, or false. Other values will | |
| 89 result in runtime errors.* | |
| 90 | |
| 91 If the skia library detects a skia.conf file at initialization time, it will | |
| 92 parse it and override the default values of any declared configuration variables | |
| 93 with the values found in the file. | |
| 94 | |
| 95 *Note: although it might appear that the configuration variables have a | |
| 96 hierarchical naming scheme involving periods, that's just a convention I have | |
| 97 adopted so that when all declared configuration variables are sorted | |
| 98 alphabetically, they are roughly grouped by component.* | |
| 99 | |
| 100 ## Using environment variables | |
| 101 | |
| 102 You can quickly override the value of one runtime-configurable variable using an | |
| 103 environment variable equal to the variable's key with "skia." prepended. So, for | |
| 104 example, one might run: | |
| 105 | |
| 106 <!--?prettify?--> | |
| 107 ~~~~ | |
| 108 prompt% skia.gpu.printShaders=true out/Debug/dm | |
| 109 ~~~~ | |
| 110 | |
| 111 or | |
| 112 | |
| 113 <!--?prettify?--> | |
| 114 ~~~~ | |
| 115 prompt% export skia.gpu.printShaders=true | |
| 116 prompt% out/Debug/dm | |
| 117 ~~~~ | |
| 118 | |
| 119 On many shells, it is illegal to have a period in an environment variable name, | |
| 120 so skia also supports underscores in place of the periods: | |
| 121 | |
| 122 <!--?prettify?--> | |
| 123 ~~~~ | |
| 124 prompt% skia_gpu_printShaders=true out/Debug/dm | |
| 125 ~~~~ | |
| 126 | |
| 127 or | |
| 128 | |
| 129 <!--?prettify?--> | |
| 130 ~~~~ | |
| 131 prompt% export skia_gpu_printShaders=true` | |
| 132 prompt% out/Debug/dm | |
| 133 ~~~~ | |
| 134 | |
| 135 ## Discovering all possible configuration variables | |
| 136 | |
| 137 As this system becomes more widely used in skia, there may be hundreds of | |
| 138 configuration variables. What are they all? What are their defaults? What do | |
| 139 they do? | |
| 140 | |
| 141 In order to find out, simply create a zero-length skia.conf file \(on unix, | |
| 142 `touch skia.conf` will do the trick\). If skia detects a zero-length | |
| 143 configuration file, it will overwrite it with a sorted list of all known | |
| 144 configuration variables, their defaults, and their description strings. Each | |
| 145 line will be commented out and have its value already equal to its default, so | |
| 146 you can then edit this file to your liking. | |
| 147 | |
| 148 To trigger this behavior, call the function | |
| 149 `skRTConfRegistry().possiblyDumpFile(); ` or simply use `SkAutoGraphics | |
| 150 ag;`, which also validates your configuration and print out active non-default | |
| 151 options. | |
| 152 | |
| 153 ## Are these things enabled all the time? | |
| 154 | |
| 155 No, they are only enabled in builds where SK_DEBUG is defined. This includes bot
h | |
| 156 `Debug` and `Release_Developer` gyp BUILDTYPES. The `Release_Developer` build ty
pe | |
| 157 has exactly the same build flags as `Release`, except it re-enables SK_DEBUG, wh
ich | |
| 158 in turn enables runtime configuration behavior. | |
| 159 Specifically: | |
| 160 | |
| 161 <!--?prettify?--> | |
| 162 ~~~~ | |
| 163 prompt% ninja -C BUILDTYPE=Release_Developer | |
| 164 ~~~~ | |
| 165 | |
| 166 ... wait a long time ... | |
| 167 | |
| 168 <!--?prettify?--> | |
| 169 ~~~~ | |
| 170 prompt % skia_gpu_printShaders=true out/Release_Developer/dm | |
| 171 ~~~~ | |
| 172 | |
| 173 ... enjoy ... | |
| 174 | |
| 175 ## Known issues / limitations | |
| 176 | |
| 177 Lines in 'skia.conf', including comments, are limited to 1024 characters. | |
| 178 Runtime configuration variables of type `char \* ` cannot currently have spaces | |
| 179 in them. | |
| 180 Runtime variables are only fully supported for `int`, `unsigned int`, `float`, | |
| 181 `double`, `bool`, and `char \*`. | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2212473002:
SkRTConf: eliminate (Closed)
Base URL: https://skia.googlesource.com/skia.git@master