Riley.h

Go to the documentation of this file.

/*
# ------------------------------------------------------------------------------
#
# Copyright (c) 2020 Pixar. All rights reserved.
#
# The information in this file (the "Software") is provided for the exclusive
# use of the software licensees of Pixar ("Licensees").  Licensees have the
# right to incorporate the Software into other products for use by other
# authorized software licensees of Pixar, without fee. Except as expressly
# permitted herein, the Software may not be disclosed to third parties, copied
# or duplicated in any form, in whole or in part, without the prior written
# permission of Pixar.
#
# The copyright notices in the Software and this entire statement, including the
# above license grant, this restriction and the following disclaimer, must be
# included in all copies of the Software, in whole or in part, and all permitted
# derivative works of the Software, unless such copies or derivative works are
# solely in the form of machine-executable object code generated by a source
# language processor.
#
# PIXAR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL PIXAR BE
# LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
# OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.  IN NO CASE WILL
# PIXAR'S TOTAL LIABILITY FOR ALL DAMAGES ARISING OUT OF OR IN CONNECTION WITH
# THE USE OR PERFORMANCE OF THIS SOFTWARE EXCEED $50.
#
# Pixar
# 1200 Park Ave
# Emeryville CA 94608
#
# ------------------------------------------------------------------------------
*/

/*
 * Version 0.4
 *
 * This is a preview release and is not supported.  This API will change substantially in the next
 * release of RenderMan.
 * Names, namespaces, methods, parameters, types, enums, and the structure of the interface itself
 * are expected to change.
 *
 */

#ifndef Riley_h
#define Riley_h

#include "Riley_version.h"  // Riley versioned namespace

#include "RileyIds.h"

#include "RiTypesHelper.h"  // RtUString
#include "RixInterfaces.h"

RILEY_NAMESPACE_ENTER


//
// Result types.
//
enum class CameraResult
{
    k_Error,
    k_Success
};

enum class ClippingPlaneResult
{
    k_Error,
    k_Success
};

enum class CoordinateSystemResult
{
    k_Error,
    k_Success
};

enum class DisplacementResult
{
    k_Error,
    k_Success,
    k_ResendPrimVars
};

enum class DisplayResult
{
    k_Success,
    k_Error,
};

enum class RenderViewResult
{
    k_Error,
    k_Success
};

enum class DisplayFilterResult
{
    k_Error,
    k_Success
};

enum class GeometryPrototypeResult
{
    k_Error,
    k_Success,
    k_ResendPrimVars
};

enum class GeometryInstanceResult
{
    k_Error,
    k_Success,
    k_ResendPrimVars
};

enum class IntegratorResult
{
    k_Error,
    k_Success
};

enum class LightInstanceResult
{
    k_Error,
    k_Success,
    k_ResendPrimVars
};

enum class LightShaderResult
{
    k_Error,
    k_Success,
    k_ResendPrimVars
};

enum class MaterialResult
{
    k_Error,
    k_Success,
    k_ResendPrimVars
};

enum class RenderOutputResult
{
    k_Success,
    k_Error,
    k_ErrorRenderTargetAttached,
    k_ErrorDisplayAttached
};

enum class RenderTargetResult
{
    k_Success,
    k_Error,
    k_ErrorDisplayAttached
};

enum class SampleFilterResult
{
    k_Error,
    k_Success
};

enum class StopResult
{
    k_Success,
    k_NotRendering,
};

//
// Input types.
//
struct Extent
{
    uint32_t x;
    uint32_t y;
    uint32_t z;
};

struct FilterSize
{
    float width;
    float height;
};

enum class RenderOutputType
{
    k_Float,    // 32-bit single precision floating point number
    k_Integer,  // 32-bit one's complement integer
    k_Color,    // 3-k_Float
    k_Vector    // 3-k_Float
};

struct ShadingNode;
struct ShadingNetwork
{
    uint32_t nodeCount;
    ShadingNode const* nodes;
};

struct ShadingNode
{
    enum class Type
    {
        k_Invalid,
        k_Pattern,
        k_Bxdf,
        k_Integrator,
        k_Light,
        k_LightFilter,
        k_Projection,
        k_Displacement,
        k_SampleFilter,
        k_DisplayFilter
    };

    Type type;
    RtUString name;
    RtUString handle;
    RtParamList params;
};

struct Transform
{
    uint32_t samples;
    RtMatrix4x4 const* matrix;
    float const* time;
};

//
// List types.
// Multiple APIs require a list of ids. Declaring an explicit type of these yields clearer code.
//
struct CoordinateSystemList
{
    uint32_t count;
    CoordinateSystemId const* ids;
};

struct DisplayFilterList
{
    uint32_t count;
    DisplayFilterId const* ids;
};

struct SampleFilterList
{
    uint32_t count;
    SampleFilterId const* ids;
};

struct RenderOutputList
{
    uint32_t count;
    RenderOutputId const* ids;
};

struct RenderViewList
{
    uint32_t count;
    RenderViewId const* ids;
};

struct GeometryInstanceCreateData
{
    UserId userId;

    GeometryPrototypeId groupPrototypeId;

    GeometryPrototypeId geoPrototypeId;

    MaterialId materialId;

    CoordinateSystemList const* coordsysList;

    Transform const* xform;

    RtParamList const* attributes;
};

struct GeometryInstanceModifyData
{
    GeometryPrototypeId groupPrototypeId;

    GeometryInstanceId instanceId;  

    MaterialId const* materialId;   

    CoordinateSystemList const* coordsysList;  

    Transform const* xform;

    RtParamList const* attributes;
};

struct GeometryInstanceDeleteData
{
    GeometryPrototypeId groupPrototypeId;

    GeometryInstanceId instanceId;
};

struct LightInstanceCreateData
{
    UserId userId;

    GeometryPrototypeId groupPrototypeId;

    GeometryPrototypeId geoPrototypeId;

    MaterialId materialId;

    LightShaderId lightShaderId;

    CoordinateSystemList const* coordsysList;

    Transform const* xform;

    RtParamList const* attributes;
};

struct LightInstanceModifyData
{
    GeometryPrototypeId groupPrototypeId;

    LightInstanceId lightInstanceId;

    MaterialId const* materialId;

    LightShaderId const* lightShaderId;

    CoordinateSystemList const* coordsysList;

    Transform const* xform;

    RtParamList const* attributes;
};

struct LightInstanceDeleteData
{
    GeometryPrototypeId groupPrototypeId;

    LightInstanceId lightInstanceId;
};

// Additional batch interface list types.
// Multiple APIs require a list of ids. Declaring an explicit type of these yields clearer code.

struct GeometryInstanceCreateList
{
    size_t count;
    GeometryInstanceCreateData const* elems;
};

struct GeometryInstanceModifyList
{
    size_t count;
    GeometryInstanceModifyData const* elems;
};

struct GeometryInstanceDeleteList
{
    size_t count;
    GeometryInstanceDeleteData const* elems;
};

struct GeometryInstanceIdList
{
    size_t count;
    GeometryInstanceId* ids;
};

struct GeometryInstanceResultList
{
    size_t count;
    GeometryInstanceResult* results;
};

struct LightInstanceCreateList
{
    size_t count;
    LightInstanceCreateData const* elems;
};

struct LightInstanceModifyList
{
    size_t count;
    LightInstanceModifyData const* elems;
};

struct LightInstanceDeleteList
{
    size_t count;
    LightInstanceDeleteData const* elems;
};

struct LightInstanceIdList
{
    size_t count;
    LightInstanceId* ids;
};

struct LightInstanceResultList
{
    size_t count;
    LightInstanceResult* results;
};

class Riley
{
public:
    virtual ~Riley(){};


    virtual void Render(RenderViewList const& renderViews, RtParamList const& renderOptions) = 0;

    virtual StopResult RequestUpdate() = 0;

    virtual StopResult Stop() = 0;

    virtual bool SetRenderSettings(RtParamList const& renderOptions) = 0;

    virtual bool SetRenderMetadata(CameraId id, RtParamList const& metadata) = 0;
    virtual bool SetRenderMetadata(GeometryPrototypeId groupId, GeometryInstanceId id,
                                   RtParamList const& metadata) = 0;
    virtual bool SetRenderMetadata(GeometryPrototypeId id, RtParamList const& metadata) = 0;
    virtual bool SetRenderMetadata(MaterialId id, RtParamList const& metadata) = 0;
    virtual bool SetRenderMetadata(DisplacementId id, RtParamList const& metadata) = 0;
    virtual bool SetRenderMetadata(IntegratorId id, RtParamList const& metadata) = 0;
    virtual bool SetRenderMetadata(LightInstanceId id, RtParamList const& metadata) = 0;
    virtual bool SetRenderMetadata(LightShaderId id, RtParamList const& metadata) = 0;
    virtual bool SetRenderMetadata(CoordinateSystemId id, RtParamList const& metadata) = 0;
    virtual bool SetRenderMetadata(RenderOutputId id, RtParamList const& metadata) = 0;
    virtual bool SetRenderMetadata(RenderTargetId id, RtParamList const& metadata) = 0;
    virtual bool SetRenderMetadata(DisplayId id, RtParamList const& metadata) = 0;


    virtual void SetOptions(RtParamList const& sceneOptions) = 0;

    virtual void InvalidateTexture(RtUString const filename) = 0;

    virtual RenderOutputId CreateRenderOutput(  //
        UserId userId, RtUString name, RenderOutputType type, RtUString source,
        RtUString accumulationRule, RtUString filter, FilterSize const& filterSize,
        float relativePixelVariance, RtParamList const& params) = 0;

    virtual RenderOutputResult ModifyRenderOutput(  //
        RenderOutputId renderOutput, RtUString const* name, RenderOutputType const* type,
        RtUString const* source, RtUString const* accumulationRule, RtUString const* filter,
        FilterSize const* filterSize, float const* relativePixelVariance, RtParamList const* params) = 0;

    virtual RenderOutputResult DeleteRenderOutput(RenderOutputId renderOutput) = 0;

    virtual RenderTargetId CreateRenderTarget(  //
        UserId userId, RenderOutputList const& renderOutputs, Extent const& extent,
        RtUString filterMode, float pixelVariance, RtParamList const& params) = 0;

    virtual RenderTargetResult ModifyRenderTarget(  //
        RenderTargetId renderTarget, RenderOutputList const* renderOutputs, Extent const* extent,
        RtUString const* filterMode, float const* pixelVariance, RtParamList const* params) = 0;

    virtual RenderTargetResult DeleteRenderTarget(RenderTargetId renderTarget) = 0;

    virtual DisplayId CreateDisplay(  //
        UserId userId, RenderTargetId renderTarget, RtUString name, RtUString driver,
        RenderOutputList const& renderOutputs, RtParamList const& driverParams) = 0;

    virtual DisplayResult ModifyDisplay(  //
        DisplayId display, RenderTargetId const* renderTarget, RtUString const* name,
        RtUString const* driver, RenderOutputList const* renderOutputs,
        RtParamList const* driverParams) = 0;

    virtual DisplayResult DeleteDisplay(DisplayId display) = 0;

    virtual RenderViewId CreateRenderView(  //
        UserId userId, RenderTargetId renderTargetId, CameraId cameraId, IntegratorId integratorId,
        DisplayFilterList const& displayFilters, SampleFilterList const& sampleFilters,
        RtParamList const& params) = 0;

    virtual RenderViewResult ModifyRenderView(  //
        RenderViewId renderViewId, RenderTargetId const* renderTargetId, CameraId const* cameraId,
        IntegratorId const* integratorId, DisplayFilterList const* displayFilters,
        SampleFilterList const* sampleFilters, RtParamList const* params) = 0;

    virtual RenderViewResult DeleteRenderView(RenderViewId renderViewId) = 0;

    virtual DisplayFilterId CreateDisplayFilter(  //
        UserId userId, ShadingNetwork const& displayFilter, RtParamList const& attributes) = 0;

    virtual DisplayFilterResult ModifyDisplayFilter(  //
        DisplayFilterId displayFilterId, ShadingNetwork const* displayFilter,
        RtParamList const* attributes) = 0;

    virtual DisplayFilterResult DeleteDisplayFilter(DisplayFilterId displayFilterId) = 0;

    virtual SampleFilterId CreateSampleFilter(  //
        UserId userId, ShadingNetwork const& sampleFilter, RtParamList const& attributes) = 0;

    virtual SampleFilterResult ModifySampleFilter(  //
        SampleFilterId sampleFilterId, ShadingNetwork const* sampleFilter,
        RtParamList const* attributes) = 0;

    virtual SampleFilterResult DeleteSampleFilter(SampleFilterId sampleFilterId) = 0;

    virtual CameraId CreateCamera(  //
        UserId userId, RtUString name, ShadingNode const& projection, Transform const& xform,
        RtParamList const& properties) = 0;

    virtual CameraResult ModifyCamera(  //
        CameraId cameraId, ShadingNode const* projection, Transform const* xform,
        RtParamList const* properties) = 0;

    virtual void DeleteCamera(CameraId cameraId) = 0;

    // A clipping plane should be specified by a transform only. 'params' allows for optional values
    // to be provided, either for backward compatibility (i.e. provide a plane normal and origin
    // point), or to support future features (e.g. use a clipping portal, different shapes, etc...).
    virtual ClippingPlaneId CreateClippingPlane(  //
        Transform const& xform, RtParamList const& params) = 0;
    virtual ClippingPlaneResult ModifyClippingPlane(  //
        ClippingPlaneId clippingPlaneId, Transform const* xform, RtParamList const* params) = 0;
    virtual ClippingPlaneResult DeleteClippingPlane(ClippingPlaneId clippingPlaneId) = 0;

    virtual void SetDefaultDicingCamera(CameraId cameraId) = 0;

    virtual IntegratorId CreateIntegrator(UserId userId, ShadingNode const& integratorNode) = 0;

    virtual IntegratorResult ModifyIntegrator(  //
        IntegratorId integratorId, ShadingNode const* integratorNode) = 0;

    virtual IntegratorResult DeleteIntegrator(IntegratorId integratorId) = 0;

    virtual CoordinateSystemId CreateCoordinateSystem(  //
        UserId userId, Transform const& xform, RtParamList const& attributes) = 0;

    virtual CoordinateSystemResult ModifyCoordinateSystem(  //
        CoordinateSystemId coordsysId, Transform const* xform, RtParamList const* attributes) = 0;

    virtual void DeleteCoordinateSystem(CoordinateSystemId coordsysId) = 0;

    virtual DisplacementId CreateDisplacement(  //
        UserId userId, ShadingNetwork const& displacement, RtParamList const& attributes) = 0;

    virtual DisplacementResult ModifyDisplacement(  //
        DisplacementId displacementId, ShadingNetwork const* displacement,
        RtParamList const* attributes) = 0;

    virtual void DeleteDisplacement(DisplacementId displacementId) = 0;

    virtual LightShaderId CreateLightShader(  //
        UserId userId, ShadingNetwork const& light, ShadingNetwork const& lightFilter) = 0;

    virtual LightShaderResult ModifyLightShader(  //
        LightShaderId lightShaderId, ShadingNetwork const* light,
        ShadingNetwork const* lightFilter) = 0;

    virtual void DeleteLightShader(LightShaderId lightShaderId) = 0;

    virtual MaterialId CreateMaterial(  //
        UserId userId, ShadingNetwork const& bxdf, RtParamList const& attributes) = 0;

    virtual MaterialResult ModifyMaterial(  //
        MaterialId materialId, ShadingNetwork const* bxdf, RtParamList const* attributes) = 0;

    virtual void DeleteMaterial(MaterialId materialId) = 0;

    virtual GeometryPrototypeId CreateGeometryPrototype(  //
        UserId userId, RtUString type, DisplacementId displacementId,
        RtPrimVarList const& primvars) = 0;

    virtual GeometryPrototypeResult ModifyGeometryPrototype(  //
        RtUString type, GeometryPrototypeId geoPrototypeId, DisplacementId const* displacementId,
        RtPrimVarList const* primvars) = 0;

    virtual void DeleteGeometryPrototype(GeometryPrototypeId geoPrototypeId) = 0;

    virtual GeometryInstanceId CreateGeometryInstance(  //
        UserId userId, GeometryPrototypeId groupPrototypeId, GeometryPrototypeId geoPrototypeId,
        MaterialId materialId, CoordinateSystemList const& coordsysList, Transform const& xform,
        RtParamList const& attributes) = 0;

    virtual GeometryInstanceResult ModifyGeometryInstance(  //
        GeometryPrototypeId groupPrototypeId, GeometryInstanceId instanceId,
        MaterialId const* materialId, CoordinateSystemList const* coordsysList,
        Transform const* xform, RtParamList const* attributes) = 0;

    virtual void DeleteGeometryInstance(  //
        GeometryPrototypeId groupPrototypeId, GeometryInstanceId instanceId) = 0;

    virtual LightInstanceId CreateLightInstance(  //
        UserId userId, GeometryPrototypeId groupPrototypeId, GeometryPrototypeId geoPrototypeId,
        MaterialId materialId, LightShaderId lightShaderId,
        CoordinateSystemList const& coordsysList, Transform const& xform,
        RtParamList const& attributes) = 0;

    virtual LightInstanceResult ModifyLightInstance(  //
        GeometryPrototypeId groupPrototypeId, LightInstanceId lightInstanceId,
        MaterialId const* materialId, LightShaderId const* lightShaderId,
        CoordinateSystemList const* coordsysList, Transform const* xform,
        RtParamList const* attributes) = 0;

    virtual void DeleteLightInstance(  //
        GeometryPrototypeId groupPrototypeId, LightInstanceId lightInstanceId) = 0;

    virtual void CreateGeometryInstances(GeometryInstanceCreateList const& instances,
                                         GeometryInstanceIdList& ids) = 0;

    virtual void ModifyGeometryInstances(GeometryInstanceModifyList const& instances,
                                         GeometryInstanceResultList& results) = 0;

    virtual void DeleteGeometryInstances(GeometryInstanceDeleteList const& instances) = 0;

    virtual void CreateLightInstances(LightInstanceCreateList const& instances,
                                      LightInstanceIdList& ids) = 0;

    virtual void ModifyLightInstances(LightInstanceModifyList const& instances,
                                      LightInstanceResultList& results) = 0;

    virtual void DeleteLightInstances(LightInstanceDeleteList const& instances) = 0;
};

RILEY_NAMESPACE_HEADER_EXIT

class RixRileyManager : public RixInterface
{
public:
    virtual riley::Riley* CreateRiley(RtUString rendervariant, RtParamList const& params) = 0;
    virtual void DestroyRiley(riley::Riley* rl) = 0;

    virtual void GetOptionOverrides(RtParamList& options) const = 0;

protected:
    RixRileyManager() : RixInterface(2)
    {}
};

#endif