|
| 1 | + **osltoy** |
| 2 | + revision date: 30 Nov 2017 |
| 3 | + |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | +_osltoy_ basics |
| 8 | +================================================== |
| 9 | + |
| 10 | +`osltoy` is an interactive editor and realtime visualizer for OSL shaders. |
| 11 | +It is inspired by [Shadertoy](https://www.shadertoy.com/) by Inigo Quilez. |
| 12 | +But it uses a real VFX shading language! |
| 13 | + |
| 14 | +![osltoy](Figures/osltoy/osltoy-fbm.jpg width="400px") |
| 15 | + |
| 16 | +The basic functionaity of `osltoy` is: |
| 17 | + |
| 18 | +* Allow you to edit OSL shader source code. |
| 19 | +* Live and continuous rendering of an "image" that is the result of running |
| 20 | + your shader on each pixel of the image (pixel color is taken from the |
| 21 | + shader's parameter `output color Cout`.) |
| 22 | + |
| 23 | + |
| 24 | +## Command line |
| 25 | + |
| 26 | +Launch `osltoy` from the command line: |
| 27 | + |
| 28 | +`osltoy` [*options*] |
| 29 | + |
| 30 | +Additional command line arguments: |
| 31 | + |
| 32 | +`--help` |
| 33 | +: Print command line options and other help. |
| 34 | + |
| 35 | +`-v` |
| 36 | +: Verbose mode. (Doesn't really do anything currently.) |
| 37 | + |
| 38 | +`--res` *xres* *yres* |
| 39 | +: Specifies the resolution of the render window (default: 512 x 512). |
| 40 | + |
| 41 | +`--threads` *n* |
| 42 | +: Specifies the number of simultaneous threads to use for shading. If not |
| 43 | + specified, it will use all your hardware cores. |
| 44 | + |
| 45 | +*filename.osl* |
| 46 | +: If one or more filenames of shader source code are specified, they will |
| 47 | + be loaded into editor tabs upon startup. |
| 48 | + |
| 49 | + |
| 50 | +## osltoy Basics |
| 51 | + |
| 52 | +First, let's launch `osltoy`: |
| 53 | + |
| 54 | +``` |
| 55 | +$ osltoy |
| 56 | +``` |
| 57 | + |
| 58 | +![ ](Figures/osltoy/osltoy-start.jpg width="400px") |
| 59 | +This will start up a new `osltoy` session. |
| 60 | +On the right half of the GUI is a code editor window. Below the code editor |
| 61 | +is an area that will show you any compilation errors. The left half of the |
| 62 | +GUI will display the results of the shader (a checkerboard if no shader |
| 63 | +has been compiled yet). Below that is an area that will hold widgets to |
| 64 | +allow adjustment of shader parameter values. |
| 65 | + |
| 66 | +At the very bottom of the app window is a status bar showing time, frames |
| 67 | +per second, and other status messages. At the very top of the app window |
| 68 | +(or, on MacOS, at the top of the screen) is a menu bar with the usual set of |
| 69 | +common operations. |
| 70 | + |
| 71 | +### Loading and saving shaders |
| 72 | + |
| 73 | +You can load a shader one of three ways: |
| 74 | + |
| 75 | +1. Specify the filename of an existing shader when you launch the app: |
| 76 | + ``` |
| 77 | + osltoy test.osl |
| 78 | + ``` |
| 79 | + |
| 80 | +2. From a blank window, load an existing shader by selecting the menu |
| 81 | + bar choice `File` --> `Open`, or hitting the hotkey `Ctrl-O` (on MacOS, |
| 82 | + ⌘`-O`). This will present a file selection dialog. |
| 83 | + |
| 84 | +3. Just start typing in the editor window. |
| 85 | + |
| 86 | +You can save the edited shader with the menu bar `File` --> `Save` |
| 87 | +or the hotkey `Ctrl-S` (⌘`-S` on MacOS). If the file does not yet |
| 88 | +have a name, you will be presented with a file save dialog (as you will |
| 89 | +if you use `File` --> `Save As`). |
| 90 | + |
| 91 | +!!! Note |
| 92 | + Every time we talk about a `Ctrl-`*key* combination, if you are on MacOS |
| 93 | + (OSX), that hotkey will be ⌘`-`*key*. This document won't awkwardly |
| 94 | + repeat this clarification for every command. |
| 95 | + |
| 96 | +### Compiling shaders |
| 97 | + |
| 98 | +When you have loaded or edited your OSL source code, you can compile the |
| 99 | +shader with menu `Tools` --> `Recompile shaders`, or by clicking the |
| 100 | +`Recompile` button below the source code editor widget, or by using the |
| 101 | +hotkey `Ctrl-R`. |
| 102 | + |
| 103 | +!!! Warning |
| 104 | + `osltoy` won't compile a buffer that doesn't have a filename ending in |
| 105 | + `.osl`, and if you started with a blank window, it won't have a name at |
| 106 | + all until you save the first time. |
| 107 | + |
| 108 | +In the compilation status window below the editor, you will either see |
| 109 | +an `Ok` message if the compiler succeeded, or the error output from the |
| 110 | +compiler, as illustrated here: |
| 111 | + |
| 112 | +![Compilation error display.](Figures/osltoy/osltoy-error.jpg width="512px") |
| 113 | + |
| 114 | + |
| 115 | +!!! Warning |
| 116 | + `osltoy` appears to let you load or create multiple shaders, appearing |
| 117 | + in a tabbed editor. We'll get this working eventually (so you can edit |
| 118 | + whole shader groups and all the shaders that are in them), but currently |
| 119 | + only the shader in the first tab will be compiled and executed, so don't |
| 120 | + get confused by the non-functional parts of the interface. |
| 121 | + |
| 122 | + |
| 123 | +### Executing shaders and interactive changes |
| 124 | + |
| 125 | +Once you compile the shader successfully, it will execute and display the |
| 126 | +results of shading a rectangle. |
| 127 | + |
| 128 | + |
| 129 | + |
| 130 | +As soon as you recompile, the shader will be executed as quickly as possible |
| 131 | +and displayed as an image on the left, with shader parameter adjustment |
| 132 | +widgets below it. |
| 133 | + |
| 134 | +Evey time you change a parameter value through its widget, the shader will |
| 135 | +automatically recompile and re-execute. If you edit the text of the shader, |
| 136 | +clicking the `Recompile` button or using the hotkey `Ctrl-R` will recompile |
| 137 | +and re-execute the shader. |
| 138 | + |
| 139 | + |
| 140 | +Rules of the game |
| 141 | +================== |
| 142 | + |
| 143 | +## Shader inputs and state |
| 144 | + |
| 145 | +The shader is executed on every pixel of an image (defaulting to a 512x512 |
| 146 | +square, but you can change the resolution via a command line flag). |
| 147 | + |
| 148 | +The `float u` and `v` global variables vary from 0 to 1 along the rectangle. |
| 149 | + |
| 150 | +The `point P` global variable will be set to `(x,y,0)`, where `x` is the pixel |
| 151 | +horizontal coordinate (0 to xres-1 as it goes from left to right) and `y` |
| 152 | +is the pixel vertical coordinate (0 to yres-1 as it goes from top to bottom |
| 153 | +of the image). |
| 154 | + |
| 155 | +The `float time` global variable contains the time (in seconds) since the |
| 156 | +last time the shader was recompiled. Making your shader change its behavior |
| 157 | +based on the `time` variable will make an animated shader. |
| 158 | + |
| 159 | +## Shader outputs |
| 160 | + |
| 161 | +The color displayed is taken from the shader output parameter that is |
| 162 | +declared like this: |
| 163 | + |
| 164 | +``` |
| 165 | + output color Cout = 0 |
| 166 | +``` |
| 167 | + |
| 168 | +Whatever you place in that output will be the color displayed at each pixel |
| 169 | +of the output image. |
| 170 | + |
| 171 | +!!! Note |
| 172 | + Your shader does not need to set `Ci` or deal with closures. The |
| 173 | + `osltoy` app is just for exploring pattern generation, not illumination. |
| 174 | + It doesn't actually have any notion of 3D geometry or lights. |
| 175 | + |
| 176 | + |
| 177 | +## Shader execution |
| 178 | + |
| 179 | +If your shader does not reference the `time` variable in any way, it will |
| 180 | +only be executed once each time it recompiles. But if `time` appears in your |
| 181 | +shader, it will execute repeatedly, as quickly as possible, until you exit |
| 182 | +or recompile. |
| 183 | + |
| 184 | +Shader execution will by default use enough threads to keep all your cores |
| 185 | +busy. The command line option `--threads` can be used to limit the number |
| 186 | +of cores (or to "over-thread"). |
| 187 | + |
| 188 | + |
| 189 | +Caveats, limitations, and broken stuff |
| 190 | +======================== |
| 191 | + |
| 192 | +These are current limitations or breakages that we will fix over time. |
| 193 | + |
| 194 | +* The GUI seems to let you open multiple editor tabs, but currently, the |
| 195 | + only one that will compile and execute is the *first* (farthest to the left |
| 196 | + tab that was loaded or saved under a name that ends in `".osl"`. |
| 197 | + |
| 198 | +* We intend to add "Pause" and "Reset" buttons to control time. |
| 199 | + |
| 200 | +* I tried to make the parameter adjustment widgets be clever about how |
| 201 | + quickly to modify the values, depending on their range. But I don't have |
| 202 | + it quite right. It's still being refined. |
| 203 | + |
| 204 | +* There isn't yet have a way to get the shader itself to get information about |
| 205 | + external events such as mouse clicks or key presses, but that would be |
| 206 | + fun. |
| 207 | + |
| 208 | +* There isn't yet a way for the shader to have *state* that can be computed, |
| 209 | + stored, then re-read when the shader executes on the next frame. |
| 210 | + |
| 211 | + |
| 212 | +Things to try |
| 213 | +============= |
| 214 | + |
| 215 | +* Try this: |
| 216 | + |
| 217 | + ` osltoy ` *osl_install_directory*`/shaders/mandelbrot.osl` |
| 218 | + |
| 219 | +* Use the global `time` variable to make animated patterns. |
| 220 | + |
| 221 | +* Explore noise functions and other pattern generation interactively. |
| 222 | + |
| 223 | +* Explore (by keeping an eye on the "FPS" reading at the bottom) what shader |
| 224 | + operations are fast and what is slow. |
| 225 | + |
| 226 | +* Don't forget that `texture()` calls work as expected in shadertoy! |
| 227 | + |
| 228 | +* `osltoy` is a great tool for leaning or *teaching* OSL. |
| 229 | + |
| 230 | +* The actual "geometry" is just a rectangle, but like with Shadertoy, |
| 231 | + you can make patterns that *look like* by implementing a simple ray tracer |
| 232 | + in the shader itself, or using other clever tricks. |
| 233 | + |
| 234 | +* Look at the many examples on [Shadertoy](https://www.shadertoy.com/) |
| 235 | + for inspiration! |
| 236 | + |
| 237 | +* Make crazy stuff and post the shaders to the `osl-dev` mail list! |
| 238 | + |
| 239 | + |
| 240 | + |
| 241 | +<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="markdeep.min.js"></script><script src="https://casual-effects.com/markdeep/latest/markdeep.min.js?"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script> |
| 242 | +<link rel="stylesheet" href="docs.css?"> |
| 243 | + |
0 commit comments