create_hdri_environment.literate

# Create an HDRi environment

_written by Nathan 'jesterKing' Letwory_

The `RenderEnvironment`  represents environments in Rhino. To create an
environment that uses an HDRi texture we'll be creating the `RenderTexture` that
holds that HDRi image, and the `RenderEnvironment` to which we will assign that
texture.

We'll be creating the `RenderEnvironment` using
[`RenderContent.Create`](https://mcneel.github.io/rhinocommon-api-docs/api/RhinoCommon/html/M_Rhino_Render_RenderContent_Create_5.htm)
that takes a GUID, in this case the `RenderEnvironment` GUID which is `ba51ce00-ba51-ce00-ba51-ceba51ce0000`, content chooser flags that we leave at `NONE` and a `RhinoDoc` instance that we get from `scriptcontext`.

To create the HDR render texture we'll be using
[`RenderContentType.NewContentFromTypeId`](https://mcneel.github.io/rhinocommon-api-docs/api/RhinoCommon/html/M_Rhino_Render_RenderContentType_NewContentFromTypeId.htm)
to which we will pass `Rhino.Render.ContentUuids.HDRTextureType`.

```py : <<create an HDRi environment.*>>= ./create_hdri_environment.py $ template=rhipysrc.template
import scriptcontext as sc
import Rhino
import System

file_dialog = Rhino.UI.OpenFileDialog()
file_dialog.Filter = "EXR (*.exr)|*.exr"
if file_dialog.ShowDialog():
  <<create HDR texture>>
  <<create environment>>
  <<assign HDR to environment>>
```

## Creating the HDR texture

As mentioned earlier we'll be directly creating the texture through
`RenderContentType`, giving it the correct GUID.

``` py : <<create HDR texture>>=
render_texture = Rhino.Render.RenderContentType.NewContentFromTypeId(
  Rhino.Render.ContentUuids.HDRTextureType
)
```

Once we have a new instance we set the `filename` parameter to a string that is
the path to an HDRi file. To set parameters we need to bracket the call to
`SetParameter` in a `BeginChange` and `EndChange` pair.

Additionally we'll also change the texture saturation to show how that can be
done. The parameter name is `rdk-texture-adjust-saturation`.

``` py : <<create HDR texture>>=+
render_texture.BeginChange(Rhino.Render.RenderContent.ChangeContexts.Program)
render_texture.SetParameter("filename", file_dialog.FileName)
render_texture.SetParameter("rdk-texture-adjust-saturation", 0.0)
render_texture.EndChange()
```

## Creating the environment

``` py  : <<create environment>>=
render_environment = Rhino.Render.RenderContent.Create(
  System.Guid('ba51ce00-ba51-ce00-ba51-ceba51ce0000'),
  Rhino.Render.RenderContent.ShowContentChooserFlags.NONE,
  sc.doc
  )
```

## Assigning the texture

Assigning the texture to the environment we do using `SetChild` to the child
with name `texture`.


``` py  : <<assign HDR to environment>>=
render_environment.BeginChange(Rhino.Render.RenderContent.ChangeContexts.Program)
render_environment.SetChild(render_texture, "texture")
render_environment.EndChange()
```

## The final script

The Python-only code for this literate program can be found [here](https://github.com/jesterKing/rhipy/blob/master/create_hdri_environment.py).