1 // Copyright Contributors to the Open Shading Language project. 2 // SPDX-License-Identifier: BSD-3-Clause 3 // https://github.com/AcademySoftwareFoundation/OpenShadingLanguage 4 5 #pragma once 6 7 8 OSL_NAMESPACE_ENTER 9 10 struct ClosureColor; 11 class ShadingContext; 12 class RendererServices; 13 14 15 16 /// Type for an opaque pointer to whatever the renderer uses to represent a 17 /// coordinate transformation. 18 typedef const void* TransformationPtr; 19 20 21 22 /// The ShaderGlobals structure represents the state describing a particular 23 /// point to be shaded. It serves two primary purposes: (1) it holds the 24 /// values of the "global" variables accessible from a shader (such as P, N, 25 /// Ci, etc.); (2) it serves as a means of passing (via opaque pointers) 26 /// additional state between the renderer when it invokes the shader, and 27 /// the RendererServices that fields requests from OSL back to the renderer. 28 /// 29 /// Except where noted, it is expected that all values are filled in by the 30 /// renderer before passing it to ShadingSystem::execute() to actually run 31 /// the shader. Not all fields will be valid in all contexts. In particular, 32 /// a few are only needed for lights and volumes. 33 /// 34 /// All points, vectors and normals are given in "common" space. 35 /// 36 struct ShaderGlobals { 37 /// Surface position (and its x & y differentials). 38 Vec3 P, dPdx, dPdy; 39 /// P's z differential, used for volume shading only. 40 Vec3 dPdz; 41 42 /// Incident ray, and its x and y derivatives. 43 Vec3 I, dIdx, dIdy; 44 45 /// Shading normal, already front-facing. 46 Vec3 N; 47 48 /// True geometric normal. 49 Vec3 Ng; 50 51 /// 2D surface parameter u, and its differentials. 52 float u, dudx, dudy; 53 /// 2D surface parameter v, and its differentials. 54 float v, dvdx, dvdy; 55 56 /// Surface tangents: derivative of P with respect to surface u and v. 57 Vec3 dPdu, dPdv; 58 59 /// Time for this shading sample. 60 float time; 61 /// Time interval for the frame (or shading sample). 62 float dtime; 63 /// Velocity vector: derivative of position P with respect to time. 64 Vec3 dPdtime; 65 66 /// For lights or light attenuation shaders: the point being illuminated 67 /// (Ps), and its differentials. 68 Vec3 Ps, dPsdx, dPsdy; 69 70 /// There are three opaque pointers that may be set by the renderer here 71 /// in the ShaderGlobals before shading execution begins, and then 72 /// retrieved again from the within the implementation of various 73 /// RendererServices methods. Exactly what they mean and how they are 74 /// used is renderer-dependent, but roughly speaking it's probably a 75 /// pointer to some internal renderer state (needed for, say, figuring 76 /// out how to retrieve userdata), state about the ray tree (needed to 77 /// resume for a trace() call), and information about the object being 78 /// shaded. 79 void* renderstate; 80 void* tracedata; 81 void* objdata; 82 83 /// Back-pointer to the ShadingContext (set and used by OSL itself -- 84 /// renderers shouldn't mess with this at all). 85 ShadingContext* context; 86 87 /// Pointer to the RendererServices object. This is how OSL finds its 88 /// way back to the renderer for callbacks. 89 RendererServices* renderer; 90 91 /// Opaque pointers set by the renderer before shader execution, to 92 /// allow later retrieval of the object->common and shader->common 93 /// transformation matrices, by the RendererServices 94 /// get_matrix/get_inverse_matrix methods. This doesn't need to point 95 /// to the 4x4 matrix itself; rather, it's just a pointer to whatever 96 /// structure the RenderServices::get_matrix() needs to (if and when 97 /// requested) generate the 4x4 matrix for the right time value. 98 TransformationPtr object2common; 99 TransformationPtr shader2common; 100 101 /// The output closure will be placed here. The renderer should 102 /// initialize this to NULL before shading execution, and this is where 103 /// it can retrieve the output closure from after shader execution has 104 /// completed. 105 ClosureColor* Ci; 106 107 /// Surface area of the emissive object (used by light shaders for 108 /// energy normalization). 109 float surfacearea; 110 111 /// Bit field of ray type flags. 112 int raytype; 113 114 /// If nonzero, will flip the result of calculatenormal(). 115 int flipHandedness; 116 117 /// If nonzero, we are shading the back side of a surface. 118 int backfacing; 119 }; 120 121 122 123 /// Enum giving values that can be 'or'-ed together to make a bitmask 124 /// of which "global" variables are needed or written to by the shader. 125 enum class SGBits { 126 None = 0, 127 P = 1 << 0, 128 I = 1 << 1, 129 N = 1 << 2, 130 Ng = 1 << 3, 131 u = 1 << 4, 132 v = 1 << 5, 133 dPdu = 1 << 6, 134 dPdv = 1 << 7, 135 time = 1 << 8, 136 dtime = 1 << 9, 137 dPdtime = 1 << 10, 138 Ps = 1 << 11, 139 Ci = 1 << 12, 140 last 141 }; 142 143 OSL_NAMESPACE_EXIT 144