# Adding Textures to the Ocean Surface

To accomodate textures attached to the ocean surface, the non-functional parameter line of the ocean file previously called "cusps" has been replaced with a ``texture'' flag. Input files not using textures can remain just as before.

Textures are locked onto the ocean surface at the position and orientation desired by the user, and undulate with the ocean surface. The user has the option of placing the texture as if it is on the underside or the topside of the interface. For example, when the texture is placed on the underside of the ocean surface and the camera is above looking down, the texture appears to be floating just under the waves.

If textured oceans are not wanted, then the relavant portion of the ocean input file is

  `...`
  `whitecaps no`
  `texture no`
  `sunbeams no`
  `...`

(``texture'' used to be ``cusps no'').

For textured oceans, the format is:

  `...`
  `whitecaps` no
  `texture` yes
  `RenderWorld_data_file texture 2 2`
  `surface_type ocean`
  `nTextures` 1
  `xyOrigin` 0 0
  `Theta` 0
  `dimensions` 10 10
  `periodic` 1
  `animate` 0
  `new_picture` 0
  `pictureFile` k.rgb
  `priority` 0
  `nBands` `3`
  `viewAbove` yes
  `multiplyReflectance` 0
  `alphaAbove` 1
  `min_radiance_above` 0 0 0
  `max_radiance_above` 10 10 10
  `viewBelow` no
  `endTexture`
  `sunbeams no`
  `...`

The only option for the parameter `surface_type` is `ocean` at present. `nTextures` is the number of textures to be placed on the surface. For each one`xyOrigin` is the center position of the texture relative to the ocean position, in physical units (meters). `Theta` is in degrees, and is the rotation angle of the texture relative to the ocean grid. `dimensions` are x,y lengths in meters. Textures are "stretched" when these proportions don't match the picture aspect ratio.

When `periodic` 1 is chosen, the texture is reproduced as an infinitely repeating tile, whereas `periodic` 0 provides only a single copy of the texture.

The `animate` option allows the texture to be moved along the surface. Animation is accomplished by setting its value to 1 and adding three new parameters as follows,

  `animate` 1
  `Vx` 10.0
  `Vy` 3.0
  `to` 0.0

  `Vx` and `Vy` represent the velocities of the texture is meters/second and represents the time at which the texture starts moving. Its location at `to` is the value specified by `xyOrigin`.

  The `new_picture` parameter allows you to have the texture vary from frame to frame. This is accomplished by setting `new_picture` to 1 and adding a line to specify the base name of the file as follows,

  `new_picture` 1
  `pictureBase` k

  For each frame the texture is taken from a file that is constructed from the pictureBase (k) and the four digit frame number XXXX as k.XXXX.rgb. Note that each of these images must be the same size and that `pictureFile` must still be specified in order for RenderWorld to initialize the mcodeory necessary to hold the texture.

  The texure to be used is an rgb or rgba image which is named on the `pictureFile` line.

  When there are multiple overlapping textures, the `priority` provides ranking of the textures to determine which is rendered in front of the others. The highest priority texture map within each pixel is imaged first.

  `nBands` is the number of color bands. As with the other input files, this number is typically 3.

  The choice `viewAbove` yes allows the texture to be visible from above the surface, and is followed by an additional four parameters. The alternative, `viewAbove` no, has no additional parameters, and the texture map is not visible (transparent) from above. Similarly, the line `viewBelow` determines whether the texture map is visible from beneath the ocean surface, and if the answer is yes, then a set of four additional parameters follow.

  When the texture map can be viewed, the parameter `multiplyReflec` determines whether the texture map appears to be on the same or opposite side of the water surface as the camera. Thus `multiplyReflec` 1 eans that the texture is on the opposite side, and `multiplyReflec` 0 means the texture is on the same side as the camera.

  The line `alphaAbove` determines whether the alpha channel in an rgba texture image should be used to attenuate the water light. The possible options for `alphaAbove` are:

  `alphaAbove` 0 do not use the alpha channel

  `alphaAbove` 1 use the alpha channel to block the background

  `alphaAbove` 2 use the alpha channel to block the background and condition the texture.

  As an sgi image, the texture map must be converted to radiometric units as part of the rendering process. The parameters `minRadAbove`, and `maxRadAbove` provide the scaling of the sgi rgb images to radiance units.

  If `viewBelow` is yes an additional 5 lines must be included just as with the `viewAbove` case.

  Above and below have different alphas and different scalings, but the same texture map. You can have different texture maps if you specify two textures and choose "above yes" for one and "below yes" for the other.

  An example of a full texture input that enables both animation and new pictures is

  `RenderWorld_data_file texture 2 2`
  `surface_type ocean`
  `nTextures 1`
  `xyOrigin 0 0`
  `Theta 270`
  `dimensions 25 25`
  `periodic 0`
  `animate 1`
  `Vx 10.0`
  `Vy 3.0`
  `to 0.0`
  `new_picture 1`
  `pictureBase k`
  `pictureFile k.0001.rgb`
  `priority 3`
  `nBands 3`
  `viewAbove yes`
  `multiplyReflectance 0`
  `alphaAbove 1`
  `min_radiance_above 0 0 0`
  `max_radiance_above 15 15 15`
  `viewBelow no`
  `endTexture`

  Contents