initCopyright ©1995 by NeXT Computer, Inc. All Rights Reserved.
| N3DShader |
| Inherits From: | Object | |
| Declared In: | 3Dkit/N3DShader.h |
| Class Description |
| N3DShader manages the application of shader functions to N3DShapes. A shader function is written in the RenderMan Shading Language, compiled with the shading language compiler (see the shader(1) UNIX manual page), and contained in a shading language object file. The RenderMan Shading Language is described in detail in The RenderMan Companion.
Shader Functions and Shading Language Object Files Each N3DShader instance manages a single shading language function. A shader function is contained in a shading language object file. The name of the shader function and shading language object file are the same (the file name has the extension .slo). When its shader function is set by the initWithShader: or setShader: methods, an N3DShader searches for the specified shader language object file in the current directory, and in the directory paths ~/Library/Shaders, /LocalLibrary/Shaders, and /NextLibrary/Shaders. If the specified shader is found, the N3DShader's type, along with its arguments and their default values, is set. The N3DShader class provides methods to determine these arguments for a particular shader function and to assign values for these arguments. When rendering, the argument/value pairs are passed to the shader function. You can reset any of an N3DShader's arguments to their default values using the resetShaderArg: method.
Shader Function Arguments Each shader function can have an open-ended list of arguments. The N3DShader class provides a number of methods for accessing these arguments and setting or retrieving their values. The method shaderArgCount returns the number of arguments for the function. The method shaderArgNameAt: returns the name of each argument by zero-based index. The method shaderArgType: returns the type of a named argument. The N3DShader class provides several methods to let you get and set the values for named arguments to a shader function. These methods perform type conversion between the C-language, NEXTSTEP, and RenderMan types used in your application and the RenderMan Shading Language types used in the underlying shading function. The shading language argument types are identified by members of an enumeration, SLO_TYPE, declared in the header file ri/slo.h. The following table lists the correspondences between C-language types, shading language types, and methods: |
| C-language Type | SLO_TYPE | Methods | |
| RtPoint | SLO_TYPE_POINT | getShaderArg:pointValue: setShaderArg:pointValue: | |
| NXColor | SLO_TYPE_COLOR | getShaderArg:colorValue: setShaderArg:colorValue: | |
| float | SLO_TYPE_SCALAR | getShaderArg:floatValue: setShaderArg:floatValue: | |
| const char * | SLO_TYPE_STRING | getShaderArg:stringValue: setShaderArg:stringValue: |
| In general, you should use the shaderArgType: method to check an argument's type, then use the getShaderArg:... and setShaderArg:... method appropriate to the type of the argument. While it's recommended that your application enforce these correspondences, the type conversion provided with each of the getShaderArg:... and setShaderArg:... methods is flexible enough to let you mix ostensibly incompatible data types. The conversion schemes are somewhat complex but are documented with each of the getShaderArg:... and setShaderArg:... for the sake of completeness.
N3DShader and N3DShape RenderMan Shading Language functions are applied to specific surfaces in a scene. In the 3D Graphics Kit, N3DShaders are applied by being associated with N3DShapes. As the shapes in a shape hierarchy are rendered, the associated shader functions are called: The shaders are thereby applied to that shape and its descendants. Each N3DShape can apply six different shader types: |
| surface displacement light imager volume transformation |
| See the description of the render: method in N3DShape for an illustration of the order in which a shape's shader functions are invoked.
N3DShader and the Interactive Renderer While the PhotoRealistic RenderMan renderer can use any shader written with the RenderMan Shading Language, the Interactive RenderMan renderer uses only a limited set of shaders. The surface type shaders that can be used by the interactive renderer are constant, matte, metal, plastic, and none. The atmosphere shaders used by the interactive renderer are depthcue and fog. Other than these, the interactive renderer ignores shading functions for performance reasons. |
| Instance Variables |
| NXColor color;
float transparency; const char *shader; SLO_TYPE shaderType; int shaderArgCount; SLOArgs *shaderArgs; NXZone *zone; |
| color | Shader color | |
| transparency | Shader transparency | |
| shader | Name of the shader function | |
| shaderType | Type of shader | |
| shaderArgCount | Size of the array of shader arguments | |
| shaderArgs | Array of shader arguments | |
| zone | The zone in which the object's data resides |
| Method Types |
| Initializing and freeing | init |
| initWithShader: free |
| Shader language object file | setShader: |
| shader |
| Shader color | setColor: |
| color setUseColor: doesUseColor |
| Shader transparency | setTransparency: |
| transparency |
| Shader function argument handling |
| shaderArgCount |
| shaderArgNameAt: shaderArgType: isShaderArg: setShaderArg:floatValue: setShaderArg:stringValue: setShaderArg:pointValue: setShaderArg:colorValue: getShaderArg:floatValue: getShaderArg:stringValue: getShaderArg:pointValue: getShaderArg:colorValue: resetShaderArg: |
| Shader type | shaderType | |
| Invoking the shader function | set | |
| Archiving | read: |
| write: |
| Instance Methods |
| color |
| (NXColor)color |
| Returns the color of the shader.
See also: |
| doesUseColor |
| (BOOL)doesUseColor |
| Returns YES if the shader uses colors; NO if not.
See also: |
| free |
| free |
| Frees the N3DShader and its data. |
| getShaderArg:colorValue: |
| getShaderArg:(const char *)colorName colorValue:(NXColor *)colorValue |
| Returns by reference the colorValue of the shader argument colorName. This method should be used for shader function arguments of SLO_TYPE_COLOR. Use the method shaderArgType: to check colorName's type before invoking this method. See "Shader Function Arguments" in the class description for a more complete discussion of how to get the type of an argument.
If the argument colorName isn't a color type, this method converts the shading language type to an NXColor. If the argument is a float, the argument's value is converted using the NXConvertGrayToColor() function. If the argument is a string, the string value is converted to a float and then converted to a color with NXConvertGrayToColor(). If the argument is a point, its x-, y-, and z-coordinates are treated as r-, g-, and b-components and converted by the function NXConvertRGBToColor(). Returns self. See also: |
| getShaderArg:floatValue: |
| getShaderArg:(const char *)floatName floatValue:(float *)floatValue |
| Returns by reference the floatValue of the shader argument floatName. This method should be used for shader function arguments of SLO_TYPE_SCALAR. Use the method shaderArgType: to check floatName's type before invoking this method. See "Shader Function Arguments" in the class description for a more complete discussion of how to get the type of an argument.
If the argument floatName isn't a float, this method converts the shading language type to a float. If the argument is a color, the value is converted using the NXConvertColorToGray() function. If the argument is a string, the string value is converted to a float. If the argument is a point, its x-coordinate is returned. Returns self. See also: |
| getShaderArg:pointValue: |
| getShaderArg:(const char *)pointName pointValue:(RtPoint *)pointValue |
| Returns by reference the pointValue of the shader argument pointName. This method should be used for shader function arguments of SLO_TYPE_POINT. Use the method shaderArgType: to check colorName's type before invoking this method. See "Shader Function Arguments" in the class description for a more complete discussion of how to get the type of an argument.
If the argument pointName isn't a point type, this method converts the shading language type to an RtPoint. If the argument is a color, the the r-, g-, and b-components of the color are assigned to the x-, y-, and z-cooordinates of pointValue. If the argument is a float, all three components of pointValue return that value. If the argument is a string, the string value is converted to and treated as a float. Returns self. See also: |
| getShaderArg:stringValue: |
| getShaderArg:(const char *)stringName stringValue:(const char **)stringValue |
| Returns by reference the stringValue of the shader argument stringName. This method should be used for shader function arguments of SLO_TYPE_STRING. Use the method shaderArgType: to check stringName's type before invoking this method. See "Shader Function Arguments" in the class description for a more complete discussion of how to get the type of an argument.
If the argument stringName isn't a string type, this method converts the shading language type to a string. If the argument is a point, the string returned contains the x-, y-, and z-coordinates in order. If the argument is a color, the string returned contains the r-, g-, and b-components in order. If the argument is a float, the string returned contains the value. Returns self. See also: |
| init |
| init |
| Initializes the receiver, a newly allocated instance of N3DShader. The shader name is set to NULL. The receiver's color is set to white and its transparency set to opaque (1.0).
See also: |
| initWithShader: |
| initWithShader:(const char *)aShader |
| Initializes the receiver, a newly allocated instance of N3DShader. Invokes setShader: to set the receiver's shader to aShader. |
| isShaderArg: |
| (BOOL)isShaderArg:(const char *)argName |
| Returns YES if argName is the name of an argument for the shader owned by the N3DShader. |
| read: |
| read:(NXTypedStream *)stream |
| Reads the receiver from the typed stream stream. Returns self.
See also: |
| resetShaderArg: |
| resetShaderArg:(const char *)argName |
| Restores the default value for the shader argument argName. |
| set |
| set |
| Applies the receiver's shader function during rendering. This method calls the appropriate RenderMan function--RiSurface(), RiAtmosphere(), and so on--with the N3DShader's shader name and arguments. If the receiver is set to apply its color, this method calls RiColor() before calling the shader function.
An N3DShape can have one each of six different N3DShader types. This method is invoked by N3DShape's render: method on each of its N3DShader instances before the shape renders itself. Returns self. See also: |
| setColor: |
| setColor:(NXColor)aColor |
| Sets the color of the N3DShader to aColor. Note that the effect produced by this method is distinct from that of setShaderArg:colorValue:, which is used to set an argument/value pair for a shader function. Returns self.
See also: |
| setShader: |
| setShader:(const char *)aShader |
| Sets the receiver's shader function to aShader. aShader must be the name of a shader language object file in the default shader search path. Shader language object files are created by the shader compiler; each contains a single shader function. |
| setShaderArg:colorValue: |
| setShaderArg:(const char *)colorName colorValue:(NXColor)colorValue |
| Sets the value of the shader argument colorName. This method should be used for shader function arguments of SLO_TYPE_COLOR. Use the method shaderArgType: to check colorName's type before invoking this method. See "Shader Function Arguments" in the class description for a more complete discussion of how to get the type of an argument.
If the argument colorName isn't a color, this method converts colorValue to the appropriate shading language type. If the argument is a float, colorValue is converted using the NXConvertColorToGray() function. If the argument is a string, colorValue's r-, g-, and b-components are placed in the string in order. If the argument is a point, the r-, g-, and b-components of colorValue are set as the x-, y-, and z-components of the argument. Returns self. See also: |
| setShaderArg:floatValue: |
| setShaderArg:(const char *)floatName floatValue:(float)floatValue |
| Sets the value of the shader argument floatName. This method should be used for shader function arguments of SLO_TYPE_SCALAR. Use the method shaderArgType: to check colorName's type before invoking this method. See "Shader Function Arguments" in the class description for a more complete discussion of how to get the type of an argument.
If the argument floatName isn't a float, this method converts floatValue to the appropriate shading language type. If the argument is a color, floatValue is converted using the NXConvertGrayToColor() function. If the argument is a string, floatValue is converted to a string. If the argument is a point, all three coordinates are set to floatValue. Returns self. See also: |
| setShaderArg:pointValue: |
| setShaderArg:(const char *)pointName pointValue:(RtPoint)pointValue |
| Sets the value of the shader argument pointName. This method should be used for shader function arguments of SLO_TYPE_POINT. Use the method shaderArgType: to check pointName's type before invoking this method. See "Shader Function Arguments" in the class description for a more complete discussion of how to get the type of an argument.
If the argument pointName isn't a point, this method converts pointValue to the appropriate shading language type. If the argument is a float, pointValue's x-coordinate is assigned to the variable. If the argument is a string, the x-, y-, and z-coordinates of pointValue are placed in order in the string. If the argument is a color, this method assigns the x-, y-, and z-coordinates of pointValue to the r-, g-, and b-components of the argument. Returns self. See also: |
| setShaderArg:stringValue: |
| setShaderArg:(const char *)stringName stringValue:(const char *)stringValue |
| Sets the value of the shader argument stringName. This method should be used for shader function arguments of SLO_TYPE_STRING. Use the method shaderArgType: to check stringName's type before invoking this method. See "Shader Function Arguments" in the class description for a more complete discussion of how to get the type of an argument.
If the argument stringName is a float, this method converts stringValue to a float. If the argument is a point or color, no conversion is made and the argument's value isn't changed. Returns self. See also: |
| setTransparency: |
| setTransparency:(float)alphaValue |
| Sets the transparency of the shader to alphaValue. Returns self. |
| setUseColor: |
| setUseColor:(BOOL)flag |
| If flag is YES, sets the receiver to apply its color when rendering. The color is set with the setColor: method, and is applied using the RiColor() RenderMan call. Normally, this method is only invoked with flag YES for a surface type N3DShader. Note that the effect produced by this method is distinct from that of setShaderArg:colorValue:, which is used to set an argument/value pair for a shader function.
See also: |
| shader |
| (const char *)shader |
| Returns the name of the shader function associated with the N3DShader. |
| shaderArgCount |
| (int)shaderArgCount |
| Returns the number of arguments for the shader function associated with the N3DShader. |
| shaderArgNameAt: |
| (const char *)shaderArgNameAt:(int)argIndex |
| Returns the name of the argument at position argIndex in the list of shader function argument names. To get all argument names, use this method to iterate through the list beginning with an argIndex of 0 and ending with an argIndex of |
[self shaderArgCount]-1
| shaderArgType: |
| (SLO_TYPE)shaderArgType:(const char *)argName |
| Returns the type of the argument argName from the list of shader function argument names. The value returned is an enumerated type, defined in the header file ri/slo.h. If argName isn't found in the list, returns SLO_TYPE_UNKNOWN. |
| shaderType |
| (SLO_TYPE)shaderType |
| Returns the type of the shader function. The value returned is an enumerated type, defined in the header file ri/slo.h. If the receiving N3DShader doesn't have an associated shader function, this method returns SLO_TYPE_UNKNOWN. |
| transparency |
| (float)transparency |
| Returns the transparency (alpha) value set for the receiving N3DShader. |
| write: |
| write:(NXTypedStream *)stream |
| Writes the receiving N3DShader to the typed stream stream. Returns self.
See also: |