Specifying Objects, Components, and Contexts

 Add comments
 

Nau allows users to access objects, and their fields (components) inside a XML project and material library. For instance a shader may need to access the camera’s direction, or we may want to display a color in the interface.

The following objects can be accessed in a XML project or Lua script: BUFFER, BUFFER_BINDING, BUFFER_MATERIAL, CAMERA, COLOR, IMAGE_TEXTURE, LIGHT, PASS, PASS_POST_PROCESS_BUFFER, PASS_POST_PROCESS_TEXTURE, PASS_PRE_PROCESS_BUFFER, PASS_PRE_PROCESS_TEXTURE, RENDERER, RENDER_TARGET, SCENE, SCENE_OBJECT, SPHERE, STATE, TEXTURE, TEXTURE_BINDING, TEXTURE_MATERIAL, VIEWPORT.

To access a component of an object we need to first specify which particular object we want. This is defined in the context field. The name of the object, as defined in the XML file is one option for this field. Another option is “CURRENT”. This mode allows access to the current object, where current is the object currently set in the renderer.

Consider a pass with a camera. When the pass is being renderered, the pass becomes the current pass, and the camera becomes also the current camera.

For instance to define a uniform variable named Pos with the position of the current camera we may write

<valueof uniform="Pos"
 	type="CAMERA" 
	context="CURRENT" 
	component="POSITION" />

The same goal can be achieved specifying the name of the camera, as defined in the assets section of the project.

<valueof uniform="Pos"
 	type="CAMERA" 
	context="MyCamera" 
	component="POSITION" />

The result is the same, but the previous definition is more generic as the uniform will be correctly set for passes with different cameras.

A pass contains scenes, which are composed of meshes associated with materials. Rendering a mesh implies rendering all its meshes. When rendering a mesh, its associated material also becomes the current material. The material’s elements (color, state, buffers, textures and image textures) can be accessed using CURRENT as well.

For instance to pass the diffuse color as specified in the current material to a uniform variable diff we can write:

<valueof uniform="diffuse"
	type="COLOR" 
	context="CURRENT"
	component="DIFFUSE" />

The same logic applies to the interface elements and optix variables. Lua scripting interface follows the same rules, with scripts having access to components of objects (current, or by name), and also being able to set their values.

The full list of object types and components is presented below. Note that some objects are read only, i.e. can not be set in the XML project, nor using lua scripts, or modified by the interface windows.:
Object Type and Components:

BUFFER

  • CLEAR (read/write) – ENUM {NEVER BY_FRAME } default: NEVER
  • DIM (read/write) – UIVEC3 default: (1, 1, 1)
  • ID (read only) – INT default: -1
  • SIZE (read/write) – UINT default: 0
  • STRUCT_SIZE (read only) – UINT default: 0

BUFFER_BINDING

  • BINDING_POINT (read/write) – INT default: -1
  • TYPE (read/write) – ENUM {ATOMIC_COUNTER SHADER_STORAGE } default:

BUFFER_MATERIAL

  • CLEAR (read/write) – ENUM {NEVER BY_FRAME } default: NEVER
  • DIM (read/write) – UIVEC3 default: (1, 1, 1)
  • ID (read only) – INT default: -1
  • SIZE (read/write) – UINT default: 0
  • STRUCT_SIZE (read only) – UINT default: 0

CAMERA

  • BOTTOM (read/write) – FLOAT default: -1.000000
  • ELEVATION_ANGLE (read/write) – FLOAT default: 0.000000
  • FAR (read/write) – FLOAT default: 10000.000000
  • FOV (read/write) – FLOAT default: 60.000000
  • LEFT (read/write) – FLOAT default: -1.000000
  • LOOK_AT_POINT (read/write) – VEC4 default: (0.000000, 0.000000, -1.000000, 1.000000)
  • NEAR (read/write) – FLOAT default: 1.000000
  • NORMALIZED_RIGHT (read only) – VEC4 default: (1.000000, 0.000000, 0.000000, 0.000000)
  • NORMALIZED_UP (read only) – VEC4 default: (0.000000, 1.000000, 0.000000, 0.000000)
  • POSITION (read/write) – VEC4 default: (0.000000, 0.000000, 0.000000, 1.000000)
  • PROJECTION_INVERSE_MATRIX (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]
  • PROJECTION_MATRIX (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]
  • PROJECTION_VIEW_MATRIX (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]
  • RIGHT (read/write) – FLOAT default: 1.000000
  • TOP (read/write) – FLOAT default: 1.000000
  • TS05_PVM_MATRIX (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]
  • TYPE (read/write) – ENUM {PERSPECTIVE ORTHO } default: PERSPECTIVE
  • UP (read/write) – VEC4 default: (0.000000, 1.000000, 0.000000, 0.000000)
  • VIEW (read/write) – VEC4 default: (0.000000, 0.000000, -1.000000, 0.000000)
  • VIEW_INVERSE_MATRIX (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]
  • VIEW_MATRIX (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]
  • ZX_ANGLE (read/write) – FLOAT default: 3.141593

COLOR

  • AMBIENT (read/write) – VEC4 default: (0.200000, 0.200000, 0.200000, 1.000000)
  • DIFFUSE (read/write) – VEC4 default: (0.800000, 0.800000, 0.800000, 1.000000)
  • EMISSION (read/write) – VEC4 default: (0.000000, 0.000000, 0.000000, 1.000000)
  • SHININESS (read/write) – FLOAT default: 0.000000
  • SPECULAR (read/write) – VEC4 default: (0.000000, 0.000000, 0.000000, 1.000000)

IMAGE_TEXTURE

  • ACCESS (read/write) – ENUM {READ_ONLY WRITE_ONLY READ_WRITE } default:
  • CLEAR (read/write) – BOOL default: false
  • INTERNAL_FORMAT (read/write) – ENUM {RGBA RGBA16 DEPTH_COMPONENT16 DEPTH_COMPONENT24 R8 R16 RG8 RG16 R16F R32F RG16F RG32F R8I R8UI R16I R16UI R32I R32UI RG8I RG8UI RG16I RG16UI RG32I RG32UI RGBA32F RGBA16F DEPTH_COMPONENT32F DEPTH32F_STENCIL8 RGBA32UI RGBA16UI RGBA8UI RGBA32I RGBA16I RGBA8I } default:
  • LEVEL (read/write) – UINT default: 0
  • TEX_ID (read/write) – UINT default: 0
  • UNIT (read only) – INT default: -1

LIGHT

  • AMBIENT (read/write) – VEC4 default: (0.200000, 0.200000, 0.200000, 1.000000)
  • COLOR (read/write) – VEC4 default: (1.000000, 1.000000, 1.000000, 1.000000)
  • CONSTANT_ATT (read/write) – FLOAT default: 1.000000
  • DIRECTION (read/write) – VEC4 default: (0.000000, 0.000000, -1.000000, 0.000000)
  • ENABLED (read/write) – BOOL default: true
  • ID (read only) – INT default: -1
  • LINEAR_ATT (read/write) – FLOAT default: 0.000000
  • NORMALIZED_DIRECTION (read only) – VEC4 default: (0.000000, 0.000000, -1.000000, 0.000000)
  • POSITION (read/write) – VEC4 default: (0.000000, 0.000000, 0.000000, 1.000000)
  • QUADRATIC_ATT (read/write) – FLOAT default: 0.000000
  • SPOT_CUTOFF (read/write) – FLOAT default: 180.000000
  • SPOT_DIRECTION (read/write) – VEC4 default: (0.000000, 0.000000, -1.000000, 0.000000)
  • SPOT_EXPONENT (read/write) – FLOAT default: 0.000000

PASS

  • BUFFER_DRAW_INDIRECT (read only) – UINT default: 0
  • COLOR_CLEAR (read/write) – BOOL default: true
  • COLOR_CLEAR_VALUE (read/write) – VEC4 default: (0.000000, 0.000000, 0.000000, 0.000000)
  • COLOR_ENABLE (read/write) – BOOL default: true
  • DEPTH_CLAMPING (read/write) – BOOL default: false
  • DEPTH_CLEAR (read/write) – BOOL default: true
  • DEPTH_CLEAR_VALUE (read/write) – FLOAT default: 1.000000
  • DEPTH_ENABLE (read/write) – BOOL default: true
  • DEPTH_FUNC (read/write) – ENUM {LESS NEVER ALWAYS LEQUAL EQUAL GEQUAL GREATER NOT_EQUAL } default: LESS
  • DEPTH_MASK (read/write) – BOOL default: true
  • DIM_X (read/write) – UINT default: 1
  • DIM_Y (read/write) – UINT default: 1
  • DIM_Z (read/write) – UINT default: 1
  • INSTANCE_COUNT (read/write) – UINT default: 0
  • RAY_COUNT (read/write) – INT default: -1
  • RUN_MODE (read only) – ENUM {DONT_RUN RUN_ALWAYS SKIP_FIRST_FRAME RUN_ONCE RUN_EVEN RUN_ODD } default: RUN_ALWAYS
  • STENCIL_CLEAR (read/write) – BOOL default: true
  • STENCIL_CLEAR_VALUE (read/write) – INT default: 0
  • STENCIL_DEPTH_FAIL (read/write) – ENUM {KEEP ZERO REPLACE INCR INCR_WRAP DECR DECR_WRAP INVERT } default: KEEP
  • STENCIL_DEPTH_PASS (read/write) – ENUM {KEEP ZERO REPLACE INCR INCR_WRAP DECR DECR_WRAP INVERT } default: KEEP
  • STENCIL_ENABLE (read/write) – BOOL default: false
  • STENCIL_FAIL (read/write) – ENUM {KEEP ZERO REPLACE INCR INCR_WRAP DECR DECR_WRAP INVERT } default: KEEP
  • STENCIL_FUNC (read/write) – ENUM {LESS NEVER ALWAYS LEQUAL EQUAL GEQUAL GREATER NOT_EQUAL } default: ALWAYS
  • STENCIL_OP_MASK (read/write) – UINT default: 255
  • STENCIL_OP_REF (read/write) – INT default: 0
  • TEST_MODE (read only) – ENUM {RUN_IF RUN_WHILE } default: RUN_IF

PASS_POST_PROCESS_BUFFER

  • CLEAR (read/write) – BOOL default: false

PASS_POST_PROCESS_TEXTURE

  • CLEAR (read/write) – BOOL default: false
  • CLEAR_LEVEL (read/write) – INT default: -1
  • MIPMAP (read/write) – BOOL default: false

PASS_PRE_PROCESS_BUFFER

  • CLEAR (read/write) – BOOL default: false

PASS_PRE_PROCESS_TEXTURE

  • CLEAR (read/write) – BOOL default: false
  • CLEAR_LEVEL (read/write) – INT default: -1
  • MIPMAP (read/write) – BOOL default: false

RENDERER

  • BUFFER_DRAW_INDIRECT (read/write) – UINT default: 0
  • DEBUG_DRAW_CALL (read only) – BOOL default: false
  • FRAME_COUNT (read only) – UINT default: 0
  • INSTANCE_COUNT (read/write) – UINT default: 0
  • LIGHT_COUNT (read only) – INT default: 0
  • MODEL (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]
  • MOUSE_LEFT_CLICK (read/write) – IVEC2 default: (0, 0)
  • MOUSE_MIDDLE_CLICK (read/write) – IVEC2 default: (0, 0)
  • MOUSE_RIGHT_CLICK (read/write) – IVEC2 default: (0, 0)
  • NORMAL (read only) – MAT3 default: [ 1.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 1.000000 ]
  • PROJECTION (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]
  • PROJECTION_VIEW (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]
  • PROJECTION_VIEW_MODEL (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]
  • TEXTURE (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]
  • TEXTURE_COUNT (read only) – INT default: 0
  • TIMER (read only) – FLOAT default: 0.000000
  • TS05_PVM (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]
  • VIEW (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]
  • VIEW_MODEL (read only) – MAT4 default: [ 1.000000, 0.000000, 0.000000, 0.000000
    0.000000, 1.000000, 0.000000, 0.000000
    0.000000, 0.000000, 1.000000, 0.000000
    0.000000, 0.000000, 0.000000, 1.000000 ]

RENDER_TARGET

  • CLEAR_VALUES (read/write) – VEC4 [(0.000000, 0.000000, 0.000000, 0.000000), (1.000000, 1.000000, 1.000000, 1.000000)] default: (0.000000, 0.000000, 0.000000, 0.000000)
  • LAYERS (read/write) – UINT default: 1
  • LEVELS (read/write) – UINT default: 0
  • SAMPLES (read/write) – UINT default: 0
  • SIZE (read/write) – UIVEC2 default: (0, 0)

SCENE

  • BB_CENTER (read only) – VEC3 default: (0.000000, 0.000000, 0.000000)
  • BB_MAX (read only) – VEC3 default: (-1.000000, -1.000000, -1.000000)
  • BB_MIN (read only) – VEC3 default: (1.000000, 1.000000, 1.000000)
  • ROTATE (read/write) – VEC4 default: (0.000000, 1.000000, 0.000000, 0.000000)
  • SCALE (read/write) – VEC4 default: (1.000000, 1.000000, 1.000000, 1.000000)
  • TRANSFORM_ORDER (read/write) – ENUM {T_R_S T_S_R R_T_S R_S_T S_R_T S_T_R } default: T_R_S
  • TRANSLATE (read/write) – VEC4 default: (0.000000, 0.000000, 0.000000, 0.000000)

SCENE_OBJECT

  • ROTATE (read/write) – VEC4 default: (0.000000, 0.000000, 1.000000, 0.000000)
  • SCALE (read/write) – VEC4 default: (1.000000, 1.000000, 1.000000, 1.000000)
  • TRANSFORM_ORDER (read/write) – ENUM {T_R_S T_S_R R_T_S R_S_T S_R_T S_T_R } default: T_R_S
  • TRANSLATE (read/write) – VEC4 default: (0.000000, 0.000000, 0.000000, 0.000000)

SPHERE

  • SLICES (read/write) – UINT [3, ] default: 10
  • STACKS (read/write) – UINT [2, ] default: 10

STATE

  • BLEND (read/write) – BOOL default: false
  • BLEND_COLOR (read/write) – VEC4 default: (0.000000, 0.000000, 0.000000, 0.000000)
  • BLEND_DST (read/write) – ENUM {ZERO ONE SRC_COLOR ONE_MINUS_SRC_COLOR DST_COLOR ONE_MINUS_DST_COLOR SRC_ALPHA ONE_MINUS_SRC_ALPHA DST_ALPHA ONE_MINUS_DST_ALPHA SRC_ALPHA_SATURATE CONSTANT_COLOR ONE_MINUS_CONSTANT_COLOR CONSTANT_ALPHA ONE_MINUS_CONSTANT_ALPHA } default: ZERO
  • BLEND_EQUATION (read/write) – ENUM {ADD SUBTRACT REVERSE_SUBTRACT MIN MAX } default: ADD
  • BLEND_SRC (read/write) – ENUM {ZERO ONE SRC_COLOR ONE_MINUS_SRC_COLOR DST_COLOR ONE_MINUS_DST_COLOR SRC_ALPHA ONE_MINUS_SRC_ALPHA DST_ALPHA ONE_MINUS_DST_ALPHA SRC_ALPHA_SATURATE CONSTANT_COLOR ONE_MINUS_CONSTANT_COLOR CONSTANT_ALPHA ONE_MINUS_CONSTANT_ALPHA } default: ONE
  • COLOR_MASK_B4 (read/write) – BVEC4 default: (1, 1, 1, 1)
  • CULL_FACE (read/write) – BOOL default: true
  • CULL_TYPE (read/write) – ENUM {FRONT BACK FRONT_AND_BACK } default: BACK
  • DEPTH_FUNC (read/write) – ENUM {LESS NEVER ALWAYS LEQUAL EQUAL GEQUAL GREATER NOT_EQUAL } default: LESS
  • DEPTH_MASK (read/write) – BOOL default: true
  • DEPTH_TEST (read/write) – BOOL default: true
  • ORDER (read/write) – INT default: 0
  • ORDER_TYPE (read/write) – ENUM {FRONT_TO_BACK BACK_TO_FRONT } default: FRONT_TO_BACK

TEXTURE

  • COMPONENT_COUNT (read only) – INT default: 0
  • DEPTH (read/write) – INT default: 1
  • DIMENSION (read only) – ENUM {TEXTURE_2D TEXTURE_3D TEXTURE_2D_MULTISAMPLE_ARRAY TEXTURE_2D_ARRAY TEXTURE_2D_MULTISAMPLE TEXTURE_CUBE_MAP } default: TEXTURE_2D
  • ELEMENT_SIZE (read only) – INT default: 0
  • FORMAT (read only) – ENUM {DEPTH_COMPONENT RED RGB RGBA RG DEPTH32F_STENCIL8 RED } default: RGBA
  • HEIGHT (read/write) – INT default: 1
  • ID (read only) – INT default: -1
  • INTERNAL_FORMAT (read/write) – ENUM {RGBA RGBA16 DEPTH_COMPONENT16 DEPTH_COMPONENT24 R8 R16 RG8 RG16 R16F R32F RG16F RG32F R8I R8UI R16I R16UI R32I R32UI RG8I RG8UI RG16I RG16UI RG32I RG32UI RGBA32F RGBA16F DEPTH_COMPONENT32F DEPTH32F_STENCIL8 RGBA32UI RGBA16UI RGBA8UI RGBA32I RGBA16I RGBA8I } default: RGBA
  • LAYERS (read/write) – INT default: 1
  • LEVELS (read/write) – INT default: 0
  • MIPMAP (read/write) – BOOL default: false
  • SAMPLES (read/write) – INT default: 0
  • TYPE (read only) – ENUM {BYTE UNSIGNED_BYTE SHORT UNSIGNED_SHORT INT UNSIGNED_INT FLOAT UNSIGNED_INT_8_8_8_8_REV UNSIGNED_INT_24_8 FLOAT_32_UNSIGNED_INT_24_8_REV } default: UNSIGNED_BYTE
  • WIDTH (read/write) – INT default: 1

TEXTURE_BINDING

  • UNIT (read/write) – INT default: 0

TEXTURE_MATERIAL

  • COMPONENT_COUNT (read only) – INT default: 0
  • DEPTH (read/write) – INT default: 1
  • DIMENSION (read only) – ENUM {TEXTURE_2D TEXTURE_3D TEXTURE_2D_MULTISAMPLE_ARRAY TEXTURE_2D_ARRAY TEXTURE_2D_MULTISAMPLE TEXTURE_CUBE_MAP } default: TEXTURE_2D
  • ELEMENT_SIZE (read only) – INT default: 0
  • FORMAT (read only) – ENUM {DEPTH_COMPONENT RED RGB RGBA RG DEPTH32F_STENCIL8 RED } default: RGBA
  • HEIGHT (read/write) – INT default: 1
  • ID (read only) – INT default: -1
  • INTERNAL_FORMAT (read/write) – ENUM {RGBA RGBA16 DEPTH_COMPONENT16 DEPTH_COMPONENT24 R8 R16 RG8 RG16 R16F R32F RG16F RG32F R8I R8UI R16I R16UI R32I R32UI RG8I RG8UI RG16I RG16UI RG32I RG32UI RGBA32F RGBA16F DEPTH_COMPONENT32F DEPTH32F_STENCIL8 RGBA32UI RGBA16UI RGBA8UI RGBA32I RGBA16I RGBA8I } default: RGBA
  • LAYERS (read/write) – INT default: 1
  • LEVELS (read/write) – INT default: 0
  • MIPMAP (read/write) – BOOL default: false
  • SAMPLES (read/write) – INT default: 0
  • TYPE (read only) – ENUM {BYTE UNSIGNED_BYTE SHORT UNSIGNED_SHORT INT UNSIGNED_INT FLOAT UNSIGNED_INT_8_8_8_8_REV UNSIGNED_INT_24_8 FLOAT_32_UNSIGNED_INT_24_8_REV } default: UNSIGNED_BYTE
  • WIDTH (read/write) – INT default: 1

VIEWPORT

  • ABSOLUTE_ORIGIN (read only) – VEC2 [(0.000000, 0.000000), ] default: (0.000000, 0.000000)
  • ABSOLUTE_SIZE (read only) – VEC2 [(0.000000, 0.000000), ] default: (1.000000, 1.000000)
  • CLEAR_COLOR (read/write) – VEC4 [(0.000000, 0.000000, 0.000000, 0.000000), (1.000000, 1.000000, 1.000000, 1.000000)] default: (0.000000, 0.000000, 0.000000, 0.000000)
  • FULL (read/write) – BOOL default: true
  • ORIGIN (read/write) – VEC2 [(0.000000, 0.000000), ] default: (0.000000, 0.000000)
  • RATIO (read/write) – FLOAT [0.000000, ] default: 0.000000
  • SIZE (read/write) – VEC2 [(0.000000, 0.000000), ] default: (1.000000, 1.000000)