ShaderNetworkAlgo : Add expandSplines, collapseSplines, and ...

convertToOSLConventions

Author: danieldresser-ie

include/IECoreScene/ShaderNetworkAlgo.h

@@ -76,38 +76,66 @@ IECORESCENE_API void removeComponentConnectionAdapters( ShaderNetwork *network )
 /// The name of the boolean blindData label used by add/removeComponentConnectionAdapters
 IECORESCENE_API const IECore::InternedString &componentConnectionAdapterLabel();
 
+/// Converts various aspects of how shaders are stored to be ready to pass directly to OSL.
+/// The `oslVersion` argument is used to determine how conversion is performed, and should be passed a
+/// value of `OSL_VERSION`. Conversions include:
+///
+/// - Connections involving the individual components of point/color parameters.
+///     For OSL prior to 1.10, intermediate shaders are inserted to emulate connections between components.
+///     For later versions, no new shaders are inserted, but components are renamed from our `.x, .y, .z`
+///     suffixes to OSL's `[0], [1], [2]` suffixes.
+/// - Splines
+///     We support SplineData as a parameter type. For OSL, these must be converted to 3 parameters named
+///     `<splineName>Positions`, `<splineName>Values` and `<splineName>Basis`. We also support input
+///     connections to spline Y values, specified as `<splineName>[N].y`, which currently must be implemented
+///     using an adapter shader.
+IECORESCENE_API void convertToOSLConventions( ShaderNetwork *network, int oslVersion );
+
 /// Finds connections involving the individual components of point/color parameters, and converts them
 /// for use with OSL. The `oslVersion` argument is used to determine how conversion is performed,
 /// and should be passed a value of `OSL_VERSION`. For OSL prior to 1.10, intermediate shaders are
 /// inserted to emulate connections between components. For later versions, no new shaders are inserted, but
 /// components are renamed from our `.x, .y, .z` suffixes to OSL's `[0], [1], [2]` suffixes.
-/// \todo Remove the version without the `oslVersion` argument.
+/// \deprecated: Use convertToOSLConventions instead
 IECORESCENE_API void convertOSLComponentConnections( ShaderNetwork *network );
 IECORESCENE_API void convertOSLComponentConnections( ShaderNetwork *network, int oslVersion );
 
 /// Converts from the legacy ObjectVector format previously used to represent shader networks.
 IECORESCENE_API ShaderNetworkPtr convertObjectVector( const IECore::ObjectVector *network );
 
 /// We use a convention where ramps are represented by a single SplineData in Cortex, but must be expanded
-/// out into basic types when being passed to a renderer.  We need two functions to convert back and forth.
+/// out into basic types when being passed to a renderer. We need two functions to convert back and forth.
+
 
-/// Look for parameters matching our spline convention, for any possible <prefix> :
+/// Look throughout the network for parameters matching our spline convention, for any possible <prefix> :
 /// <prefix>Positions, a float vector parameter
 /// <prefix>Values, a vector of a value type, such as float or color
 /// <prefix>Basis, a string parameter
 /// For each set of parameters found matching this convention, the 3 parameters will be replaced with one
-/// spline parameter named <prefix>.  If none are found, the input is passed through unchanged.
-IECORESCENE_API IECore::ConstCompoundDataPtr collapseSplineParameters( const IECore::ConstCompoundDataPtr& parameters );
+/// spline parameter named <prefix>. If input connections are represented using an adapter shader, they
+/// will be converted to direct connections to the spline using our support for spline element
+/// connections.
+/// If `targetPrefix` is given, only translates connections to shaders with a type starting with this string
+IECORESCENE_API void collapseSplines( ShaderNetwork *network, std::string targetPrefix = "" );
+
+/// Look throughout the network for spline parameters. If any are found, they will be expanded out into
+/// 3 parameters named <name>Positions, <name>Values and <name>Basis.
+/// We also support input connections to spline Y values, specified as `<splineName>[N].y`, which currently
+/// must be implemented by inserting an adapter shader.
+/// If `targetPrefix` is given, only translates connections to shaders with a type starting with this string
+IECORESCENE_API void expandSplines( ShaderNetwork *network, std::string targetPrefix = "" );
+
 
-/// Look for spline parameters.  If any are found, they will be expanded out into 3 parameters named
-/// <name>Positions, <name>Values and <name>Basis.  If none are found, the input is passed through unchanged.
-IECORESCENE_API IECore::ConstCompoundDataPtr expandSplineParameters( const IECore::ConstCompoundDataPtr& parameters );
+/// \deprecated: Use collapseSplines on the whole network, which can handle input connections
+IECORESCENE_API IECore::ConstCompoundDataPtr collapseSplineParameters( const IECore::ConstCompoundDataPtr& parametersData );
+
+/// \deprecated: Use expandSplines on the whole network, which can handle input connections
+IECORESCENE_API IECore::ConstCompoundDataPtr expandSplineParameters( const IECore::ConstCompoundDataPtr& parametersData );
 
 
 } // namespace ShaderNetworkAlgo
 
 } // namespace IECoreScene
 
 #include "IECoreScene/ShaderNetworkAlgo.inl"
-
 #endif // IECORESCENE_SHADERNETWORKALGO_H