Common attributes standardisation proposal

[pleprince]

Common attributes standardisation proposal

Draft 1

Table of contents

1. Motivation
2. Standard Attribute Names
   1. Renderer Infos
   2. Camera
   3. Geometry
      1. Geometric quantities
      2. Identifiers
      3. classifications
   4. Rendering

Motivation

OSL has been tremendously successful at standardising shading but there are still non standardised areas, especially around each renderer’s internal nomenclature.
Although the same compiled shaders can run in any renderer, it is difficult in 2024 to write a shader that performs correctly in multiple renderers because each renderer names primitive attributes differently and may return some quantities in different spaces.

For example, if you wish to use the surface tangent:

Renderer	OSL call
RenderMan	getattribute("builtin", "Tn", tangent)
Arnold	Vector tangent = normalize(dPdu)
Vray	Vector tangent = normalize(dPdu)
Cycles	getattribute("geom:tangent", tangent)
RedShift	Vector tangent = normalize(dPdu)
3Delight	getattribute("myUVs", uvSet); Vector tangent = normalize(Dx(uvSet));1

In this case, the shader writer hopes that u, v is not the parametric uv on meshes, otherwise dPdu may be non-smooth and pretty useless. But there is no guarantee.

Note

In the spec, u and v are "The 2D parametric coordinates of P (on the particular geometric primitive you are shading)". When dPdu is usable, it means the renderer is computing dPds/dPdt instead of dPdu/dPdv, and straying from the spec.

Standard attribute names

Here is a list of proposed names for common attributes, inspired by various sources. Of course, some of these attributes should be computed on-demand, if possible.

Renderer Infos

Shader writers have no way to tell which renderer is executing our code. I think this would be useful as there are other types of discrepancies that need to be taken care of by shader writers, like the space in which some attributes are returned or the meaning of uv (face or mesh-wide coordinates ?).

This could be fixed by adding 2 standard attributes.

Attribute	Type	Description
"osl:version"	int	Major*10000 + Minor*100 + patch.
"shader:shadername"	string	Name of the shader master.
"shader:layername"	string	Name of the layer instance.
"shader:groupname"	string	Name of the shader group.
"renderer:name"	string	lower-case name i.e. "renderman"
"renderer:version"	int	Major*10000 + Minor*100 + patch.

Camera

These attributes are already defined in the OSL standard, so this is just for completeness.

Name	Type	Description
"camera:resolution"	int[2]	Image resolution.
"camera:pixelaspect"	float	Pixel aspect ratio.
"camera:projection"	string	Projection type (e.g., "perspective", "orthographic", etc.)
"camera:fov"	float	Field of fiew.
"camera:clip_near"	float	Near clip distance.
"camera:clip_far"	float	Far clip distance.
"camera:clip"	float[2]	Near and far clip distances.
"camera:shutter_open"	float	Shutter open time.
"camera:shutter_close"	float	Shutter close time.
"camera:shutter"	float[2]	Shutter open and close times.
"camera:screen_window"	float[4]	Screen window (xmin, ymin, xmax, ymax).

Geometry

Note

We should also standardize the space in which geometric quantities are returned. It should ALWAYS be "common".

Geometric Quantities

Attribute	Type	Description
"geom:tangent"	vector	The normalised surface tangent 12.
"geom:undisplaced_P"	point	The surface position before displacement.
"geom:undisplaced_N"	normal	The surface normal before displacement.
"geom:reference_P"	normal	The surface position in reference pose in object space.
"geom:reference_N"	normal	The surface normal in reference pose in object space.
"geom:reference_WP"	normal	The surface position in reference pose in world space.
"geom:reference_WN"	normal	The surface normal in reference pose in world space.

Identifiers

Attribute	Type	Description
"geom:id"	int	A unique object id, or first part of 64 bits id.
"geom:id2"	int	The second part of a 64 bits unique object id.
"geom:instance_id"	int	A unique object instance id.
"geom:curve_id"	int	A unique curve id.
"geom:point_id"	int	A unique point id.

classifications

Attribute	Type	Description
"geom:is_mesh"	int	1 if object is a mesh, 0 otherwise
"geom:is_subdiv"	int	1 if object is a subdivision surface, 0 otherwise
"geom:is_curve"	int	1 if object is a curve, 0 otherwise
"geom:is_point"	int	1 if object is a point, 0 otherwise
"geom:is_volume"	int	1 if object is a point, 0 otherwise

Rendering

Attribute	Type	Description
"stage:displace"	int	1 if running in displacement context, 0 otherwise.
"stage:shade"	int	1 if running in shading context, 0 otherwise.
"hit:direct"	int	1 if running on a direct ray hit, 0 otherwise.
"hit:indirect"	int	1 if running on an indirect ray hit, 0 otherwise.
"hit:roughness"	int	The incoming ray's spread, with [0:1] range.

Footnotes

1. u,v are parametric, so dPdu and dPdv won't be smooth on meshes: need a uv set and compute its derivative. ↩ ↩²

2. I didn't define a bitangent attribute, as it is easily computed with N and T. ↩

[fpsunflower]

This is a really great proposal and a good initiative. Here are a few comments (including on stuff that we've already mentioned in the docs but are a bit under-specified):

"camera:resolution" I assume this refers to the "display window" (in OpenEXR terms) of the renderered image. Do we want a query for the data window? It would be a int[4] that could be bigger or smaller depending on if overscan or region rendering is happening.

"camera:fov" Does this refer to the horizontal or vertical fov? Should this query fail for ortho cameras?

"geom:tangent" Do we want to describe this more precisely? ie: normalize(dPds) ? What about situations with multiple uv sets? A possible alternative would be to provide a utility function to compute dPds for any P and s using Dx and Dy (though this could be wasted work if the renderer already maintains a normalized tangent internally). Do we want to clarify the behavior on non-meshes (hair/particles)?

Where does the 3delight expression Vector tangent = normalize(Dx(uvSet)) come from? I'm assuming its some kind of extension? The builtin Dx() call does not operate on strings (assuming uvSet is the name a of particular set of uvs). It feels like a bit of an abuse of notation, but could be an interesting proposal nonetheless.

"geom:*_id" should we comment on how stable these ids are expected to be? I'm assuming the id values should be the artist assigned ones (if available) that are stable from frame to frame even if the particle/hair count changes. Likewise for instance_id and id,id2 though in my experience having a guaranteed stable numbering here is less common.

"geom:undisplaced_P" and "geom:undisplaced_N" these are easy to provide during displacement, but require extra storage to maintain into surface shading. We should probably mention that most renderers will want to check if the shader makes these queries to decide if they should be stored.

"geom:reference_P" vs "geom:reference_WP" Its a good idea to make this distinction, maybe its worth pointing out that the object-to-world transform used between these two could be different than the current object-to-world transform. One could imagine defining a standard transform name so the transformation could happen in the shader, but I'm not sure if that adds much value and would be slower.

Should we attempt to define a set of queries for standard attributes in hair shading? Most hair generation systems have standard attributes for the position (current and reference) of the root follicle, colors, texture coordinates, etc ...

[pleprince]

Hi Chris 😃

camera:resolution:

• I don't know many use cases but this is the type of info I could use to compute a camera projection.
• I would expect camera:resolution to return the display window.
• The camera:data_window could represent the camera's overscan (the smaller data window case is already handled by the underlying texuring system), which would be useful to compute the correct fit of a projection. Can you see another use case ?
• Of course, that would only be available for OpenEXR textures and the call should return the display window when not available. Whenever possible, I prefer a conservative default that most likely won't change the computation results.

camera:fov:

• Good point, this is clearly underspecified. We might prefer camera:vertical_fov and camera:horizontal_fov.

geom:tangent:

• I think there is a need to return a smooth tangent on meshes, in case it doesn't carry an artist-authored uv set. MtoA does that and I can't see a way to do that in OSL.
• I don't think we should define a dPds/dPdt, but the spec says clearly that uv are the patch/face coordinates, even though I believe Arnold fills these values with the first UV set.
• In the general case where you could have multiple UV sets, you can compute the partial derivatives of a specific UV set with Dx()/Dy().
  • One might consider using getattribute("geom:uvSet3", st), as a way to explicitly say "this is a piece of data attached to the primitive being shaded", and thus restrict the search scope.
  • In the 3Delight case, "uvSet" was supposed to be a variable. Sorry, that wasn't clear and I will correct it.

*_id:

• In my experience, they are generally stable (a hash of the primitive path, or a numerical particle / curve ID).
• This is clearly the responsibility of the DCC app feeding the renderer and no garantee can be made.

geom:undisplaced_P and geom:undisplaced_N:

• In RenderMan RIS, these quantities were not stored so we would have to call getattribute("P", undisplacedP) to make the renderer re-interpolate the original primvar (It may not be the case in XPU). That is akin to on-demand generation (with a moderate cost) but a more standard interface would be nice and increase that data's discoverability for would-be shader writers.

geom:reference_P vs. geom:reference_WP:

• Shouldn't they always be provided in "common" space to avoid any ambiguity ?

Hair shading

Oh yes, great point Chris !
I think hair shading mostly needs:

• per-curve root UVs, i.e. the surface's st coordinates at the root position for texturing.
• per-curve stable id, to generate controlled random variations.

Is there anything else ?

root uv coordinates

• The most generic thing would be geom:curve_root_uv, but it precludes filtered texture lookups, as it doesn't carry meaningful derivatives (at least in RenderMan). That is one of the reasons why I implemented a (non-ideal) max resolution texture lookup control. If there is a solution to that conundrum, it would be good to know.

uv versus st

Whenever arbitrary mapping coordinates are involved, I prefer RenderMan's classic st denomination and leave uv for the parametric coordinates.
In that regard, I would for example prefer geom:curve_root_st to geom:curve_root_uv, but I fully understand we need to take into accounts many decades of mislabeling ! 😆

[AlexeySmolenchuk]

Hi all,
My 5 cents for tangents:

Math_ComputePartialDerivativesInUvSpace() from include/osl/Math.h of RendeMan OSL examples doing a good job of extracting tangents from arbitrary uv-set, with excellent explanation. The code obviously belongs to Pixar, it would be great to have an equivalent in the std library.

[pleprince]

Thanks for pointing it out @AlexeySmolenchuk. I re-read it and realised it was a bit more involved than I thought.
@sfriedmapixar, do you think this function could be contributed to this project ?