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\) 187
