Is unmapParameterArray needed before commit? about anari-docs HOT 3 CLOSED

This ties into a larger discussion about requirements on state when calling API functions. I think it makes sense to impose some sensible restrictions to clarify expected behavior to both implementers and API users.

ANARI is required to observe state on anariRenderFrame and may observe parameter state any time after anariCommitParameters. While commits have no prescribed behavior is reasonable to expect commits to indicate meaningful state transitions and indicating the involved object is in a "usable" state. Therefore it makes sense to impose the same requirements for both anariRenderFrame and anariCommitParameters,
The requirements for both calls would be:

• Parameters must not be in a mapped state
• Array objects set as parameters must not be in a mapped state
• Required parameters are set
• All of the above apply recursively to objects set as parameters

For anariRenderFrame:

• Contributing objects must not have set but uncommitted (hanging?) parameters

Failing to meet these requirements leads to undefined behavior but the implementations are strongly encouraged to not crash and recover once the requirements are fulfilled again.

from anari-docs.

More thoughts.

An implementation that wants to eagerly prepare data structures which (also) depend on a Geometry has to react on the commit of the Geometry. There is no benefit in doing that preparation connected to a commit of the Surface, assuming the Geometry is already defined and enforcing that assumption in the spec, on the application. There may only be a single commit of the Surface, but many commits of the Geometry.

Going further, we have the same situation for Array objects (handle) as parameters. Information dependent on the content of the array (e.g., bounding box of vertex positions) needs to be (re)calculated on the unmap of the array.

One could argue, that the difference between directly mapped arrays parameters (first bullet) and array objects (handle as parameter, second bullet) is the owner of the array content, which is the parent object in the first case and the array object in the second. Yet, a re-commit of the parent object is not required when a directly mapped array changes its content, the signal of changed data from the application is again unmap (actually unmapParameterArray).

This all leads to relaxed requirements on commit. For renderFrame all involved objects need to be valid and all arrays unmapped.

from anari-docs.

Per the 5/24/23 WG call discussion, anariCommitParameters in between direct map/unmap calls is OK (though warnings ought to be emitted by the debug layer) and current spec wording is sufficient.

from anari-docs.