Devel docs remarks

[paulmelis]

Here's some things I noted in the current docs on the devel branch. Some of these are more general than specifically for 2.0, but I figured I'd list them anyway.

Incorrect:

• The bgColor parameter is listed as valid for all renderers, but the path tracer doesn't listen to it, see https://github.com/ospray/ospray/issues/347
• For isosurfaces geometry and volume texture the volume parameter needs to reference an OSPVolumetricModel apparently, although the docs say it's of type OSPVolume. For example https://github.com/ospray/ospray/blob/764afe7d094bd09324739dd678e27543b4d949f8/apps/tutorials/ospTutorialStructuredVolume.cpp#L96 This is probably due to the need for accessing the transfer function for geometry coloring?
• The signature for ospNewFrameBuffer is out of date w.r.t. ospray.h, as it uses a osp_vec2i instead of two ints

Unclear/ambiguous:

• The type of the volume and geometry parameters of an OSPGroup is listed as OSPData, so I would assume ospSetData is the right call to use, but the tutorials use ospSetObject. For example: https://github.com/ospray/ospray/blob/764afe7d094bd09324739dd678e27543b4d949f8/apps/tutorials/ospTutorialStructuredVolume.cpp#L155 How interchangeable are those two calls anyway?

• Is there a way to color an isosurface by setting a material on the GeometricModel? I.e. bypassing the TF completely for cases where one isn't needed?

• What does the path tracer's geometryLights parameter do exactly?

• The exact memory layout and semantics of an affine3f is specified nowhere, nor does ospray.h give any clues

• Is a subdivision geometry the go-to mesh structure when you don't have a pure-tri or pure-quad? Would setting level to 0 (i.e. no subdivision) give similar performance as the pure-tri/quad meshes or would it be better to convert an n-gon mesh into tris?

• Is ospCommit needed on an OSPData when it has just been created with ospNewData? From https://github.com/ospray/ospray/blob/8d5ff6d1e197f24e4ab6966ef2c5d82cbee60412/apps/tutorials/ospTutorial.c#L103-L106 it seems yes, but from https://github.com/ospray/ospray/blob/8d5ff6d1e197f24e4ab6966ef2c5d82cbee60412/apps/tutorials/ospTutorialStructuredVolume.cpp#L32-L34 it seems no.

• Is the reference count of an OSPObject influenced by ospCommit? Or is it immediately increased when doing ospSetObject/ospSetData The latter is suggested by https://github.com/ospray/ospray/blob/8d5ff6d1e197f24e4ab6966ef2c5d82cbee60412/apps/tutorials/ospTutorial.c#L113-L118, but there's also https://github.com/ospray/ospray/blob/8d5ff6d1e197f24e4ab6966ef2c5d82cbee60412/apps/tutorials/ospTutorial.c#L126-L131

Good to know:

• Color and opacity arrays given to ospNewTransferFunction do not have to have the same length
• When using imageStart and imageEnd on an OSPCamera the resulting image will show the requested cropped region of the camera frustrum, but using the full framebuffer resolution for the cropped region. This is different from having the imageStart/imageEnd specify a region in the original framebuffer before cropping (resulting in a cropped region that is a subset of the framebuffer).
• When not using the OSP_DATA_SHARED_BUFFER flag on ospNewData a copy of the source array is made. Also, if an array of OSPObject's is passed (e.g. OSPLight) all the objects in the array will have their reference count incremented.

[paulmelis]

• An spheres geometry apparently wants a sphere data array for the positions, but is listed as spheres in the docs.

[ahota]

Thanks for taking the time to make this list. We've been updating quite a few things and the documentation has gone out of sync a bit. @jeffamstutz and @johguenther can clarify more, but for some of your points:

• Isosurfaces used to take OSPVolume objects. The volume data is used to compute the implicit isosurfaces as well as coloring based on transfer function
• ospSetObject and ospSetData aren't interchangeable, so we do need to be careful about the language in the documentation regarding them. We have briefly discussed "merging" the two, but no consensus on it yet
• Spheres geometry now needs a sphere array. This one is totally on me. I headed the effort to make our public API parameter names more uniform, namely making plural names singular. I did spheres last and missed the documentation!

Thanks again for taking a look! We'll try to get these updated and clarified.

[johguenther]

ospSetObject and ospSetData are actually aliases.

[paulmelis]

https://github.com/ospray/ospray/blob/9527f27984f6ba7daeb3d64df7c0d4615866ddab/README.md#L741-L746

But an error is sent to the error handler in this case:

null handle provided to void ospRelease(OSPObject)

[johguenther]

Is there a way to color an isosurface by setting a material on the GeometricModel? I.e. bypassing the TF completely for cases where one isn't needed?

Yes, an isosurface is a geometry like all others and can get a material assigned (via the geometric model). However, a TF is currently still required for the volumetric model (we may relax this in future, in particular for this use case).

Is a subdivision geometry the go-to mesh structure when you don't have a pure-tri or pure-quad? Would setting level to 0 (i.e. no subdivision) give similar performance as the pure-tri/quad meshes or would it be better to convert an n-gon mesh into tris?

Mixed tri/quad meshes can be handled by the "mesh" geometry, higher n-gons should better be tessellated, because the subdivision geometry is rather costly.