====== Layer Definition ======

Scriptable Object asset that defines rendered layer on [[./foliage-surface]].
\\ Can be reused between multiple layers and surfaces.

To create one, **RMB in Project window > Create > Foliage Layer Definition**.

{{:foliage:layer_definition.png?direct&400|}}


----
===== Atlas =====

Each layer definition asset comes in pair with its own atlas file.
\\ When you create new layer definition, you will be prompted to create an atlas file too.
\\
\\ Atlas file is a special files used to combine textures used by definition into 2D Array by using custom asset importer.
\\ When you select atlas assed you will be able to see details about imported arrays and how much memory will they use.

{{:foliage:layer_definition_atlas_asset.png?direct&400|}}

**NOTE:** There are few different types of textures you will be assigning into plant. Textures in each type must be imported to your project with identical settings and be identical resolution - otherwise atlas generator will throw you an error with texture that is incorrect. You'll be informed whats wrong and were.
\\ 
\\ Texture types that are combined into array with atlas:
  * **Albedo Transparency** (rgba, srgb mode)
  * **Normal Map** (normal map mode)
  * **Properties Map** (rgba, linear mode)
  * **LOD Albedo** (rgb, srgb mode)

E.g. if first assigned Albedo Transparency texture is 1024x1024, then every other must be imported as 1024x1024 too. Other types can have different resolution as long as its identicall across entire texture array.
\\ 
\\ **TIP:** If you already have hi-res textures but want to have them lower resolution in atlas to save memory, simply reduce maximum resolution in each texture import settings.


----
===== Mesh Library =====

{{:foliage:layer_definition_mesh_library.png?direct&400|}}

Here you can set how many meshes will be used to render plants and assign them.
\\
\\ Ideally you will want to have only one universal mesh (e.g. flat plane) and only change displayed texture according to plant type.
\\ However, some plants looks better with different mesh and thats why you can assign multiple meshes.
\\ Each extra mesh add additional processing sub-pass which isn't great for performance, but it's cheaper and easier than having separate layer with different mesh.
\\
\\ You can set up to four meshes, but again - you should keep as few meshes as possible and reuse them by applying different textures.
\\
\\ For each mesh you can set separate (simpler) mesh that will be used to cast shadows and define if it should be rendered as double-sided or not.

==== Included Meshes ====

There are included few reusable, example meshes.
\\ This picture shows them with the idea of universal UV mapping applied on them.

{{:foliage:mesh_library.png?direct&400|}}

You can also create your own with your own UV system for your textures.
\\ To achieve this, you must follow this rule:
  * Your mesh must be size 1 along Y axis and have lowest vertex at position y=0.0 and highest at position y=1.0
    * This is required for **Upnormal Power** (see section below about plant material) and for sway animation to work properly.

{{:foliage:mesh_library_rule.png?direct&400|}}


----
===== Global Material Options =====

  * **Enable Mapping Normals** - if you disable normal maps, shader will by slightly more performant and atlas will skip these textures to save memory.
  * **Enable Mapping Properties** - if you disable properties maps, shader will by slightly more performant and atlas will skip these textures to save memory. With disabled properties mapping you will only can assign constant values per plant.
  * **Enable Virtual Plants** - virtual (mixed) plants are special plants that refer up to 3 other plants and mix them together.
  * **Simple Lit** - use simpler, Blinn-Phong lighting shader instead of PBR
  * **Environmental Reflection** - you often don't see it on such nature materials, so you can reduce shader complexity by disabling it.


----
===== Plants =====

Here you define plants.
\\ You can have up to 255 plants defined.
\\ Each time you add new plant, it gets assigned index (starting with 1).
\\ Be careful when you remove or re-order plants, because it won't update indices on surfaces and you will have to do it manually using mass tool in scene edit mode.
\\ 
\\ With **C** and **P** buttons in sidebar, you can copy and paste plant settings to another (e.g. to duplicate them).
\\ With toggle in sidebar you can enable/disable plant. Disabled plant technically is still processed and exists in memory, but its' textures will not be included in atlas. It's an alternative way to deleting plant (what would cause indices rearrangement).

==== Placement ====

{{:foliage:plant_definition_placement.png?direct&400|}}

Here you configure how this plant is placed procedurally.
  * **Mesh** - what mesh from library to use.
  * **Placement**:
    * **Density Divider** - divides density set in surface layer. Setting it to 2 gives same result as doubling density offset in layer, but without making separate layer and in general, increases performance for this plant.
    * **Width Range** - min and max scale in XZ plane.
    * **Height Range** - min and max scale in Y axis.
    * **Y Offset** - extra Y position offset for each instance. Should be 0 most of the time. See also: **Density Start Offset**
    * **Offset Variety** - should it be positioned randomly or in grid layout?
    * **Rotation Variety** - rotation randomness.
    * **Base Rotation** - base rotation.
  * **Density Affection** - by default, lower density means that less instances will be drawn. Here you can tweak that to e.g. still render all instances at lower density but with smaller scale.
    * **Stop Existance** - when density is at least this value, then all instances of plant will be visible. Otherwise, their visibility is blended between density 0 and this value. E.g when set to 0.5, then painting with density 0.5 will mean that all instances will be visible already and won't appear more with hiogher density.
    * **Start Scale Width** - width initial scale that comes with density at given area. In other words, when set to 0.0, then XZ scale is 0 at low density but **Width Range** at full density.
    * **Start Scale Height** - height initial scale that comes with density at given area. In other words, when set to 0.0, then Y scale is 0 at low density but **Height Range** at full density.
    * **Start Y Offset** - final Y Offset is actually interpolated between this value and **Y Offset** depending on density at given plant area.
  * **Adaptive Density** - here you can configure how much **Adaptive Density** will affect this plant. Takes effect only if you have enabled this feature in [[.foliage-surface]].


==== Sway ====

{{:foliage:plant_definition_sway.png?direct&400|}}

Animation parameters.

  * **Locality** - when set to 0, then sway amount is calculated and applied for "whole" plant instance identicvally. When set to 1, then sway is calculated and applied for each vertex individually.
  * **Power** - power of how much plant will sway down at full sway level. The lower value, the more flat plant will become.
  * **Wind Affection** - additional strength of global wind applied for this particular plant.
  * **Stiffness** - parameters used during simulation, but used only if interaction projector is set to Individual mode. See also: [[./interactions]].


==== Material ====

{{:foliage:plant_definition_material.png?direct&400|}}

Plant material properties.

  * **Albedo Transparency** - here you can assign color texture with opacity (must have).
    * **Gradient** - if enabled, you can set two tint colors and each instance will have random tint between these two colors.
  * **Normal Map** - here you can assign normal map
    * **Upnormal Power** - usually upper parts of plant have their normals pointing upward to reach as much sun as possible. With this value you can control how fast (according to plant height level) normal vector will go up. Low value like 0.1 means that almost entire surface will always point upwards. To disable this behaviour, put high value like 999.
  * **Properties** - here you can either assign external texture or set constant values.
    * **Texture Bias** - you can adjust each channel of texture to be more empty or full. This is usefull for **scattering**, because originally **blue channel** is unused in URP and you may already have texture with empty blue channel. In this scenariu, you can "enable" blue channel to have subsurface scattering without modyfing texture itself.
  * **UV Transform** - you can optionally set UV tiling & offset
    * All assigned textures of each type must be same size to generate atlas, but sometimes you may want to have specific plants more or less detailed. In that scenario you can prepare e.g. 1024x1024 texture that is actually atlas itself with four 512x512 textures and then use UV Transform to select final texture.
  * **Subsurface Scattering** - subsurface scattering effect.
    * Final strength of this effect depends on **scattering** property, that comes from blue channel if you assign texture. In case you have empty blue channel, use texture bias to adjust it.


==== LOD ====

{{:foliage:plant_definition_lod.png?direct&400|}}

LOD material drawn on LOD Plane.

  * **Texture, Tint, Tiling** - generic color texture setup.
  * **Density Clip** - LOD won't be rendered below this plant density.
  * **Fade Range** - how LOD fades between **Density Clip** and full plant density.
  * **Up Normal Ratio** - normals on LOD plane are about averaging normals that would come from plants themselves. 0 means that view direction will be used, 1 means that normal vector pointing upwards will be used.
  * **Height Normal Blend** - how much height normal will be blended with normal calculated above. Has affect only if you enable height normals in surface.
  * **Distance Multiplier ** - layer draw distance multiplier for LOD on this plant.
  * **Properties** - PBR material properties.


==== Virtual Plant ====

{{:foliage:plant_definition_virtual.png?direct&400|}}

Let's say you want to make giant area of grass.
\\ But, just grass will be too boring and you want to add random flowers between grass.
\\ To achieve this you can create two identical plants but with different texture - one just grass and one grass with flowers.
\\ Now you can create new plant, virtual plant, to mix these two plants together so you will end up with e.g. 90% grass and 10% flowers.
\\
\\ Virtual plants allows you to mix up to 3 different plants and still use it as one plant.
\\
\\ With virtual plants you don't configure Placement, Sway and Material tabs, but you still have to configure LOD as it's technically separate plant index.

{{:foliage:virtual_plant_example.jpg?direct&400|}}