Scene files consist of simple commands and top level elements. Examples of commands would be:

• $include
• link
• verbose
• render

Scene hierarchy depicted (that's  rootgrp & opt  at the top).

First all custom shaders that need to be linked are listed. Then the shader declaration files are included.

link "base.so"
link "mrsurfshaderlib.so"
link "mrgeolib.so"
link "mySHOW_shader.so"
$include "base.mi"
$include "mrsurfshaderlib.mi"
$include "mrgeolib.mi"
$include "mySHOW_shader.mi"

The shader declarations tell the renderer the name of the custom shader, and the names and datatypes of its parameters. Here is an example of a shader declaration from an included .mi file:

    declare shader
        color "my_material" (
            color          "ambient",
            color          "diffuse",
            color          "specular",
            scalar         "shiny",
            scalar         "reflect",
            scalar         "transparency",
            scalar         "ior",
            vector texture "bump",
            array light    "lights"
        )
        version 1
    end declare

Next is the option block, this is where rendering settings are specified, for example:

options ":myOptions"
    object space
    desaturate off
    colorclip raw
    premultiply on
    dither off
    gamma 1.
    acceleration
    bsp size 10
    bsp depth 34
    bsp memory 0
    task size 0
    contrast 0.05 0.05 0.05 0.05
    samples -1 2
    filter box 1 1
    jitter 1
    samplelock off
    scanline on
    trace on
    finalgather on
    finalgather accuracy 500 0.1
    finalgather falloff 1 40
    finalgather filter 0
    shadow off
    shadowmap off
    shadowmap rebuild off
    lens off
    volume off
    geometry on
    displace off
    output on
    merge on
    autovolume off
    face both
end options

     This is not a complete listing of all the options, to see a complete listing, along with descriptions of what each does, check section 2.7.1 Options in the Scene Entities Chapter 2 of Vol. 2. included in the printed version as well as the online manual that comes with the distribution.
     Most of the options have an equivalent on the command line, to see the syntax of the command line options, type 'ray -help'.

Next is thecamera block. A full description of camera descriptions can be found in the next section 2.7.2 Cameras of the aforementioned Scene Entities chapter.

camera "|renderCam:renderCam|renderCam:renderCamShape"
    output "+rgba_fp" "tifu" "bounce_house_1_2.tif"<-----  rendered image path
    resolution 747 450
    aperture 0.866000
    aspect 1.660000
    frame 109
    clip 1.000000 1000000.000000
    focal 0.8661417323
    offset 0.000000 0.000000
end camera

instance "camera1" "|renderCam:renderCam|renderCam:renderCamShape"  <----  instance of the camera
    visible   on     <---- check if object has primary rays on or off
    trace     on  <---- toggle for secondary rays
    shadow    on
    caustic   3
    globillum 3
    transform
        0.968583 0.00737905 0.24858 -0  <---- how camera is placed in scene
        1.55176e-18 0.99956 -0.0296717 0
        -0.24869 0.0287395 0.968157 -0
        10.472 -50.252 -52.827 1
end instance

Usually, a light definition and instance come next, although you can make GI passes that don't have any lights, for example. Anyway, a light definition is described in section 2.7.5 Lights of the Scene Entities chapter for the curious.

The texture block. After color texture, the first field is the name (which in this case is identical to the path), and the second is the path.

If the texture has the keyword "writable" in front, then it is a lightmap (baked illumination) texture. More details on textures are in section 2.7.3 Textures of the Scene Entities chapter.

color texture "/path/warehouseWN:wallC_gr:props_intwallC_gr:paintcan_2_paintcan_can.tif" "/path/warehouseWN:wallC_gr:props_intwallC_gr:paintcan_2_paintcan_can.tif"
color texture "/path/warehouseWN:wallC_gr:props_intwallC_gr:paintcan_2_paintcan_paint.tif" "/path/warehouseWN:wallC_gr:props_intwallC_gr:paintcan_2_paintcan_paint.tif"

The instance block. mental ray does not render objects (or lights or cameras) directly. Instances place an element into the scene.

If an object is defined, but has no instance, it will have no effect. An instance may consist of a geometry reference, a material reference, some flags, a transform, and other stuff.

The geometry can either be an object defined in the .mi stream with mi syntax or a shader, where the geometry is generated on the fly only if needed (function is triggered only when ray traversed bounding box). Here is what a geometry instance looks like:

instance "INST_warehouseWN:wallC_gr:intwallC_gr:paintcan_2_paintcan_can"
    geometry ="my_geo_shader"  ( or "my_previously_defined_object")
    material ["MAT_warehouseWN:wallC_gr:intwallC_gr:paintcan_2_paintcan_can"]
    visible   on
    shadow    on
    caustic   3
    globillum 3
    trace     on
  [transform matrix]
end instance

The geometry keyword refers to a geometry shader:

shader "some_paintcan"
   "my_geo_shader" (
    "file" "/path/wallC_gr:props_intwallC_gr:paintcan_2",
   "params" ...
   )

The material keyword refers to a material which in turn references a surface shader instance.

material "MAT_warehouseWN:wallC_gr:intwallC_gr:paintcan_2_paintcan_can"
   opaque = "surfmaterial_paintcan_can"
end material

shader "surfmaterial_paintcan_can"
   "surface_shader" (
    "coeff" 0.3,
    "paramcolor" 1.0 1.0 1.0
    )

The surface shader is a custom written shader.

Instance groups provide a way to structure or add hierarchy to a scene. They act much like a parent node, so that what is done to the parent is propagated to the child instances. This is where you should look if want to check which objects are being rendered - it doesn't harm to verify what your front-end 3D package is passing to mental ray. Perhaps objects that you though were turned off are still included.

It can also happen that geometry, a material, and an instance are defined in the scene, yet omitted from the instance group. This is wasteful because you still have the overhead of loading the items into the scene database, but then not rendering them.

instgroup ":myWorld"
   "INST_warehouseWN:wallC_gr:intwallC_gr:paintcan_2_paintcan_can"
   "INST_warehouseWN:wallC_gr:intwallC_gr:paintcan_2_paintcan_paint"
     .
     .
    # .   <---- if you want to temporarily prevent an object from rendering, comment it out with '#'
     .
     .
end instgroup

Finally, the render command. This tells the renderer what to render. In this case, the ":myWorld" instance group, the camera, and the options block.

render ":myWorld" "camera1" ":myOptions"