ReStructuredText | 123 lines | 93 code | 30 blank | 0 comment | 0 complexity | 6f18b266c0f982e7b6b987d43d7f9e56 MD5 | raw file
1.. 2 SPDX-License-Identifier: CC-BY-4.0 3 Copyright Contributors to the OpenColorIO Project. 4 5.. _allocationvars: 6 7How to Configure ColorSpace Allocation 8====================================== 9 10The allocation / allocation vars are utilized using during GPU 3dlut / shader 11text generation. (Processor::getGpuShaderText, Processor::getGpuLut3D). 12 13If, in the course of GPU processing, a 3D lut is required, the "allocation / 14allocation vars" direct how OCIO should sample the colorspace, with the intent 15being to maintain maximum fidelity and minimize clamping. 16 17Currently support allocations / variables: 18 19ALLOCATION_UNIFORM:: 20 2 vars: [min, max] 21 22ALLOCATION_LG2:: 23 2 vars: [lg2min, lg2max] 24 3 vars: [lg2min, lg2max, linear_offset] 25 26So say you have an srgb image (such as an 8-bit tif), where you know the data 27ranges between 0.0 - 1.0 (after converting to float). If you wanted to apply 28a 3d lut to this data, there is no danger in sampling that space uniformly and 29clamping data outside (0,1). So for this colorspace we would tag it: 30 31.. code-block:: yaml 32 33 allocation: uniform 34 allocationvars: [0.0, 1.0] 35 36These are the defaults, so the tagging could also be skipped. 37 38But what if you were actually first processing the data, where occasionally 39small undershoot and overshoot values were encountered? If you wanted OCIO to 40preserve this overshoot / undershoot pixel information, you would do so by 41modifying the allocation vars. 42 43.. code-block:: yaml 44 45 allocation: uniform 46 allocationvars: [-0.125, 1.125] 47 48This would mean that any image data originally within [-0.125, 1.125] will be 49preserved during GPU processing. (Protip: Data outside this range *may* 50actually be preserved in some circumstances - such as if a 3d lut is not needed 51- but it's not required to be preserved). 52 53So why not leave this at huge values (such as [-1000.0, 1000.0]) all the time? 54Well, there's a cost to supporting this larger dynamic range, and that cost is 55reduced precision within the 3D luts sample space. So in general you're best 56served by using sensible allocations (the smallest you can get away with, but 57no smaller). 58 59Now in the case of high-dynamic range color spaces (such as float linear), a 60uniform sampling is not sufficient because the max value we need to preserve is 61so high. 62 63Say you were using a 32x32x32 3d lookup table (a common size). Middle gray is 64at 0.18, and specular values are very much above that. Say the max value we 65wanted to preserve in our coding space is 256.0, each 3d lut lattice coordinates 66would represent 8.0 units of linear light! That means the vast majority of the 67perceptually significant portions of the space wouldn't be sampled at all! 68 69unform allocation from 0-256\: 700 718.0 7216.0 73... 74240.0 75256.0 76 77So another allocation is defined, lg2 78 79.. code-block:: yaml 80 81 - !<ColorSpace> 82 name: linear 83 description: | 84 Scene-linear, high dynamic range. Used for rendering and compositing. 85 allocation: lg2 86 allocationvars: [-8, 8] 87 88In this case, we're saying that the appropriate ways to sample the 3d lut are 89logarithmically, from 2^-8 stops to 2^8 stops. 90 91Sample locations: 922^-8\: 0.0039 932^-7\: 0.0078 942^-6\: 0.0156 95... 962^0\: 1.0 97... 982^6\: 64.0 992^7\: 128.0 1002^8\: 256.0 101 102Which gives us a much better perceptual sampling of the space. 103 104The one downside of this approach is that it can't represent 0.0, 105which is why we optionally allow a 3d allocation var, a black point 106offset. If you need to preserve 0.0 values, and you have a high 107dynamic range space, you can specify a small offset. 108 109Example: 110 111.. code-block:: yaml 112 113 allocation: lg2 114 allocationvars: [-8, 8, 0.00390625] 115 116The [-15.0, 6.0] values in spi-vfx come from the fact that all of the 117linearizations provided in that profile span the region from 2^-15 118stops, to 2^6 stops. One could probably change that black point to a 119higher number (such as -8), but if you raised it too much you would 120start seeing black values be clipped. Conversely, on the high end 121one could raise it a bit but if you raised it too far the precision 122would suffer around gray, and if you lowered it further you'd start to 123see highlight clipping.