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 In `Debug` builds, yes. `Release` builds disable runtime configuration by |
| 156 default, but it is still useful to be able to tweak certain algorithm parameters |
| 157 at runtime to do scripted performance studies. Therefore, a third build type, |
| 158 `Release_Developer` has been added. This build type has exactly the same build |
| 159 flags as `Release`, except it re-enables all runtime configuration behavior. |
| 160 Specifically: |
| 161 |
| 162 <!--?prettify?--> |
| 163 ~~~~ |
| 164 prompt% ninja -C BUILDTYPE=Release_Developer |
| 165 ~~~~ |
| 166 |
| 167 ... wait a long time ... |
| 168 |
| 169 <!--?prettify?--> |
| 170 ~~~~ |
| 171 prompt % skia_gpu_printShaders=true out/Release_Developer/dm |
| 172 ~~~~ |
| 173 |
| 174 ... enjoy ... |
| 175 |
| 176 ## Known issues / limitations |
| 177 |
| 178 Lines in 'skia.conf', including comments, are limited to 1024 characters. |
| 179 Runtime configuration variables of type `char \* ` cannot currently have spaces |
| 180 in them. |
| 181 Runtime variables are only fully supported for `int`, `unsigned int`, `float`, |
| 182 `double`, `bool`, and `char \*`. |
| 183 |
| 184 ## Questions? Bugs? Improvements? |
| 185 |
| 186 Feel free to send feedback on this system to Greg Humphreys \(humper@google\.com
\) |
OLD | NEW |