manual/render/shader_nodes/shader/ray_portal.rst

@@ -50,3 +50,49 @@ Outputs
 
 BSDF
    Standard shader output.
+
+Examples
+========
+
+One use case for the *Ray Portal BSDF* is to connect two spaces together to
+create effects like a portal to an alternative dimension, or "impossible spaces"
+where something is bigger or smaller on the inside than expected.
+
+.. figure:: /images/render_shader-nodes_ray-portal-bsdf_gateway-example.jpg
+   :width: 760px
+
+To setup a *Ray Portal BSDF* for a technique like this, you should argument the
+*Position* and *Incoming* outputs of the
+:doc:`Geometry node </render/shader_nodes/input/geometry>` to set the exit point
+and direction of the ray through the portal. Here is an example node setup:
+
+.. list-table::
+
+   * - .. figure:: /images/render_shader-nodes_ray-portal-bsdf_simple-ray-offset-nodes.jpg
+          :width: 320px
+
+          This simple node setup is used for offsetting the ray position.
+          In this example, the ray 0 units along the X axis, 4 units along
+          the Y axis, and 5 units along the Z axis.
+
+     - .. figure:: /images/render_shader-nodes_ray-portal-bsdf_ray-augmentation-nodes.jpg
+          :width: 320px
+
+          In this example, the *Location of Portal Target* and *Rotation of Portal Target*
+          vectors are obtained from a target portal object using
+          :doc:`Drivers</animation/drivers/introduction>`.
+
+Along with augmenting rays, the ray position and ray direction can be replaced,
+allowing the creation of effects like a camera feed on a screen.
+
+.. list-table::
+
+   * - .. figure:: /images/render_shader-nodes_ray-portal-bsdf_portal-to-screen-example.jpg
+          :width: 320px
+
+          Using Ray Portal BSDF to replicate the effect of a camera feed on a screen.
+
+     - .. figure:: /images/render_shader-nodes_ray-portal-bsdf_portal-to-screen-nodes.jpg
+          :width: 320px
+
+          Node setup for replicating a camera feed like effect on a screen.