/Utilities/Graphics/ShaderFeatures/ShaderFeatureFlags.cs

using System;



namespace Delta.Utilities.Graphics.ShaderFeatures

{

	/// <summary>

	/// Shader feature enum, usually multiple values are combined to define

	/// a shader ruffly. This data is mainly used for fallback generation and

	/// hints to make rendering quicker. We can skip a lot of code paths if we

	/// already know what the shader can and cannot do. For more details see

	/// the MaterialEditor tool (that can view and edit materials and shaders).

	/// Note: This enum already uses 31 bit-flags (maximum for ints, uints could

	/// be 32 bit-flags, ulong could be 64 bit-flags).

	/// </summary>

	[Flags]

	public enum ShaderFeatureFlags

	{

		#region Basic

		/// <summary>

		/// Basic shader feature always set, provides always a diffuse map.

		/// </summary>

		Basic = 0,

		#endregion



		#region UI2D

		/// <summary>

		/// By default all shaders are for 3D rendering (meshes, effects, etc.).

		/// If a shader should target 2D and more specifically UI rendering, then

		/// use this flag to make sure we only handle 2D shader code parts and

		/// also use ScreenSpace.ViewProjection2D together with

		/// Shader.Set2DRenderMatrix instead of the default

		/// ScreenSpace.ViewProjection3D.

		/// </summary>

		UI2D = 1,

		#endregion



		#region VertexCompression

		/// <summary>

		/// Normally vertex data is just a bunch of Vectors, Colors and floats

		/// in general, which works fine on fast platforms, but on lower quality

		/// mobile devices this could kill bandwidth and fill-rate, so we sometimes

		/// need to make sure that we use compressed vertex data. Please note that

		/// this flag is often set automatically for low quality mobile devices

		/// even if the shader designer did not specify it himself (which he can

		/// do both for testing and if more precision is not even required on HD

		/// shader and hints set in the MaterialEditor.

		/// </summary>

		VertexCompression = 2,

		#endregion



		#region LightMap

		/// <summary>

		/// Do we have a secondary UV texture channel for a light map? Then this

		/// flag must be set. Since dynamic lights are usually way too expensive

		/// on mobile platforms we should bake all static geometry with light maps

		/// to give games a nice look. We usually even use a little HDR in light

		/// maps, but not by providing floating point or HDR light map textures

		/// (they have too much overhead for mobile platforms), but instead by

		/// just multiplying all light map values by 4, thus the light can be

		/// darkened down if it is below 0.25, and lightened up if it is above.

		/// Animated and dynamic game objects can still have different lighting or

		/// a combination of light maps and lighting in shaders. Remember even on

		/// consoles and in big engines like Unreal light maps are used for almost

		/// everything :) If this flag is off then you are probably in some unit

		/// test, 2D code or your game is ugly :D

		/// </summary>

		LightMap = 4,

		#endregion



		#region Lighting

		/// <summary>

		/// Helper flag to indicate that this shader has no texturing, no UV

		/// channel is needed in the vertex data and the material also has no

		/// textures set (just material colors). Should be used together with the

		/// Lighting flag, else you will only see whatever static computation the

		/// pixel shader throws out (e.g. an ambient color or maybe vertex colors,

		/// which are used for line and effect shaders btw).

		/// No diffuse map is used. Even it is set in basic.

		/// </summary>

		NoTexturing = 8,



		/// <summary>

		/// Should dynamic directional lighting be used for this shader? This has

		/// the lowest impact on vertex and pixel shaders, but it still adds a

		/// few instructions. Note that any lighting calculation needs normals

		/// in the vertex data. A simple texturing shader with no flags will

		/// result in a very fast 1 pixel shader instruction shader, but adding

		/// directional lighting adds 1 or 2 pixel shader instruction (2 if the

		/// directional light contribution is calculated in the pixel shader, but

		/// it can also be done in the vertex shader, then it is just one pixel

		/// shader instruction: ambientColor + diffuseColor * lightContribution,

		/// which translates to mad r0, r0, c2, c1).

		/// </summary>

		DynamicDirectionalLighting = 16,



		/// <summary>

		/// Point lights are usually calculated (or at least pre-calculated) in

		/// the vertex shader and thus are very heavy on the computation side.

		/// They add about 20 instructions just for one point light because the

		/// light direction needs to be dynamically calculated (4 instructions).

		/// Then we need to calculate the distance and build a normal vector (3

		/// instructions) and we also need to calculate the attenuation (7

		/// instructions). And then all this needs to be applied to the final

		/// ambientDiffuseColor for the vertex for use in the pixel shader (6

		/// instructions), which adds up to 20 vertex shader instructions or even

		/// more for more complex light shaders (adding colors, fall-offs, etc.)!

		/// Some calculations can be done in the pixel shader adding a few more

		/// instructions there (e.g. applying the light normal and calculating the

		/// ambientDiffuseColor there for more realistic close up light gradients),

		/// but we should always pre-calculate the light direction and attenuation

		/// in the pixel shader. Note: If you use two dynamic point lights, use

		/// DynamicPointLight and DynamicSecondPointLight!

		/// </summary>

		DynamicPointLight = 32,



		/// <summary>

		/// Calculate a second point light, which usually adds another 10-20

		/// vertex shader instructions. See DynamicPointLight for all the notes.

		///Note: Add spot lights, more?

		/// </summary>

		DynamicSecondPointLight = 64,



		/// <summary>

		/// Hint to do the light calculation as much as possible in the pixel

		/// shader to have more accurate per pixel lighting at the cost of

		/// performance. This is usually not used, but if you have close ups

		/// or your vertices are too low for good lighting, it can be used to

		/// pretty up your final result a bit. For low quality mobile platforms

		/// this usually kills the fill-rate performance because we can only do a

		/// few pixel shader instructions, e.g. a DynamicPointLight shader with

		/// Specular turned on too adds 16 pixel shader instructions and for

		/// more than 2-3 instructions on iPad (because of the high resolution) or

		/// screen with that complex pixel shaders at 60fps anymore! Note even

		/// also all have high resolutions btw) cannot handle this kind of complex

		/// pixel shaders. You either need to make sure this is only used in

		/// specialized cases when the camera cannot go that close to objects or

		/// switch the shader if the object gets too close or just use a much

		/// lower resolution or frame rate.

		/// </summary>

		PerPixelLighting = 128,



		/// <summary>

		/// Provides ambient color and diffuse color which calculated with the

		/// diffuse map. Everything else is set by each shader feature, e.g.

		/// specular has specular color and shininess.

		/// </summary>

		AmbientDiffuse = 256,



		/// <summary>

		/// Add specular color calculation into the mix, the SpecularColor is

		/// added to the final pixel if the light reflection is right. This only

		/// makes sense if we have any lighting (DynamicDirectionalLighting or

		/// DynamicPointLight). Mostly used together with NormalMapping (which

		/// also needs lighting to work correctly) and only adds about 1 varying

		/// and maximal one instructions to the pixel shader. Specular lighting

		/// is however a little overhead in the vertex shader or even the pixel

		/// shader if PerPixelLighting is used.

		/// </summary>

		Specular = 512,



		/// <summary>

		/// Same as Specular, but instead of adding the SpecularColor at the end

		/// we multiply it with the final diffuse color. This has 4 advantages:

		/// 1. The specular effect is much weaker this way, 2. The specular color

		/// is not equally distributed, but instead depends on the texture color

		/// (black pixels get no specular, brighter ones get lightened up), 3. the

		/// vertex and pixel shader impact is usually 1 instruction less and 4.

		/// we even save one varying because we can pre-calculate this in the same

		/// ambientDiffuseColor variable we use for lighting anyway. This technique

		/// has its drawbacks obviously, it can only be used for not so shiny

		/// materials. For example metal looks much better with a Specular shader,

		/// but for some materials this technique might look good or even better.

		/// </summary>

		SpecularDiffuse = 1024,

		#endregion



		#region NormalMapping

		/// <summary>

		/// Normal mapping shader, which requires both normals (like for any

		/// lighting shaders) and also tangents (binormals are calculated in the

		/// vertex shader). Normal mapping also only makes sense if we have

		/// lights (either directional lighting or point lights). It can be

		/// combined with LightMap shaders, but there are issues there: Directional

		/// light maps are complex and not really suited for mobile platforms,

		/// even with normal light maps, normal mapping should not be used too

		/// heavily because light maps already have all lighting pre-calculated.

		/// Please also note that normal mapping adds significant overhead to

		/// the pixel shader and bandwidth because normal mapping is a per pixel

		/// operation. Diffuse (without specular) normal mapping can optimized to

		/// 4 pixel shader instructions, so it is fast enough even for slow

		/// mobile platforms if not used everywhere (together with LightMaps it

		/// might be too much both bandwidth and pixel fill rate wise). Specular

		/// normal mapping is more complex (at least 8 pixel shader instructions)

		/// and should only be used on small surfaces for slow platforms, else it

		/// might kill your performance (same tips as for PerPixelLighting apply).

		/// </summary>

		NormalMap = 2 * 1024,

		#endregion



		#region DetailMapping

		/// <summary>

		/// The Detailmap is a tiled texture that is added to improve the sharpness

		/// especially in highly scaled textures. There is a texture on which a 

		/// fine pattern is shown (usually this is a "noise" effect used). 

		/// The Detailmap is tiled over the terrain and this combined with a 

		/// diffuse mal or color map.

		/// </summary>

		DetailMapping = 4 * 1024,

		#endregion



		#region SpecularMapping

		/// <summary>

		/// Gloss (specular map) mapping effect for a directional or point light

		/// shaders. Does not add any significant pixel shader overhead, but

		/// requires a lot more bandwidth and requires content that is usually

		/// not available (has to be created on the artist side).

		/// </summary>

		SpecularMap = 8 * 1024,

		#endregion



		#region ColoredVertices

		/// <summary>

		/// Color is used for vertices, this is not really important for the

		/// final pixel output the user sees, but there are different ways

		/// rendering of colored output can be optimized. For example it is more

		/// efficient to use colored vertices for lines and effects using the

		/// same shader instead of using different AmbientColor or DiffuseColor

		/// material settings because switching materials or even updating

		/// shader parameters is very expensive, not just because you need to

		/// do the actual material update, but also because you cannot combine

		/// vertices and meshes that easily. For static or animated 3D mesh

		/// geometry on the other hand this should be used because coloring those

		/// things besides using different light sources and colors is almost non

		/// existent (if you need to use different colors for many meshes that

		/// all share the same materials otherwise, it is obviously clever again

		/// to use VertexColors instead of using many different materials).

		/// </summary>

		ColoredVertices = 16 * 1024,

		#endregion



		#region Skinning

		/// <summary>

		/// Is skinning being used? If this is on all vertices must have SkinWeight

		/// and SkinIndex data (2 floats each usually, but can also be optimized

		/// to 2 shorts each). We also need a lot of bones that need to be updated

		/// for each animated mesh and because of those bones skinning adds

		/// significant overhead to the vertex shader, which is still much better

		/// than to do all this computation on the CPU (usually a lot of vertices

		/// are affected), but obviously not as fast as static geometry!

		/// Because of this overhead the number of animated meshes should be

		/// kept as low as possible and the number of bones and vertices are also

		/// very important for fine tuning the performance on each platform.

		/// </summary>

		UseSkinning = 32 * 1024,

		#endregion



		#region Special

		/// <summary>

		/// If fog is used this flag should be set and the ShaderParameters

		/// array should contain: FogColor, FogStart and FogEnd. This does not

		/// mean those variables are used as shader uniforms, they are usually

		/// constant and can be used for both fixed function pipeline code and

		/// for shader code.

		/// Note: Currently only the FogColor is used in the shader, the rest

		/// is baked as constants into it (faster because we don't need to

		/// calculate FogEnd-FogStart and it makes more sense to have the same

		/// values for all shaders anyway).

		/// </summary>

		Fog = 64 * 1024,



		/// <summary>

		/// Use fresnel for lighting calculations, which will mostly reduce the

		/// specular color effect and show it stronger at polygons facing 90

		/// degrees away from the camera, which looks nice at silhouettes.

		/// Please note that we will completely ignore this effect for low

		/// quality platforms or if there is no lighting.

		/// </summary>

		Fresnel = 128 * 1024,



		/// <summary>

		/// Parallax mapping is usually used in combination with normal mapping,

		/// but you can use it own its own. It needs an extra height map (usually

		/// just the light map or normal map extra alpha color channel) for even

		/// cooler depth effects on the texture. Adds about 2 instructions, but

		/// even if that overhead is ok, also additional work at the artist side

		/// is needed, not only to create the extra height/bump map, but also to

		/// fine tune the parallax amount to look nice. The height map should be

		/// as blurry as possible, high variations will cause parallax glitches.

		/// </summary>

		ParallaxMap = 256 * 1024,

		// NOTE: Removed Glass, because we have no more bits.

		///// <summary>

		///// Is this shader rendering some kind of glass or transparent surface?

		///// For very low performance platforms we can ignore these materials

		///// completely (it will just be completely transparent), for medium

		///// performance platforms we can simplify this a bit (because this kind

		///// of shaders are usually slow) and for high quality platforms we can

		///// do whatever the shader wants us to do.

		///// </summary>

		//Glass = 256 * 1024,

		//Note: Removed CubeMapping

		///// <summary>

		///// By default all shaders only handle UV texture coordinates, but for

		///// cube mapping or reflection mapping we need UVW texture mapping in the

		///// VertexFormat. This flag helps us to optimize this render path and to

		///// provide a fallback shader or fallback code on non-shader platforms.

		///// </summary>

		//CubeMapping = 256 * 1024,

		/// <summary>

		/// If this is a water shader, then this is one of the most complex and

		/// advanced shaders we can do, but we still need fallbacks for slower

		/// platforms. For example on fixed function and the slowest mobile

		/// devices we just use a moving texture on the surface wobbling around,

		/// in medium platforms we might add some more pixel and vertex shader

		/// instructions for waves and all the advanced stuff can be done in

		/// specially fine tuned water shaders using pixel shader 3.0, etc.

		/// </summary>

		Water = 512 * 1024,

		//NOTE: Removed SubsurfaceScattering, because we have no more bits.

		///// <summary>

		///// Subsurface lighting shaders for light shaders. A lambertian-like

		///// surface with light "bleed-through". Useful for soft translucent

		///// materials like skin. The "subsurfaceColor" shader parameter represents

		///// the tinting acquired by light diffused below the surface. Set the

		///// "subsurfaceRollOff" angle to the cosine of the angle used for

		///// additional lighting "wraparound". The diffuse effect propagates based

		///// on the angle of LightDirection versus SurfaceNormal.

		///// </summary>

		//SubsurfaceScattering = 1024 * 1024,

		/// <summary>

		/// AlphaTest skip everything below 0.66 alpha, which is sometimes useful 

		/// for decals and models with hard alpha (trees, etc.) which look better 

		/// without having to sort anything. Examples: GlowLightEffect, 

		/// LensFlareAdditive, TreeLeavesAlphaTest, etc.

		/// </summary>

		AlphaTest = 1024 * 1024,

		//Note: Unused too right now:

		///// <summary>

		///// Use Hemisphere Lighting. This adds overhead to the vertex shader, but

		///// the pixel cost is usually very low. Currently only used for some demos

		///// and maybe very big objects in the back or the sky itself. Completely

		///// ignored on slower platforms.

		///// </summary>

		//HemisphereLighting = 2 * 1024 * 1024,

		//Note: Also unused

		///// <summary>

		///// Are we using a reflection surface? Often used together with Water,

		///// Glass or CubeMapping (then this uses a ReflectionCubeMap). Reflection

		///// can significantly add realism to a scene, but usually we need to

		///// calculate the reflection render target each frame for a realistic

		///// water for example, which adds so much overhead, it makes this technique

		///// unusable for lower quality mobile platforms. On the other hand we can

		///// use pre-calculated reflection maps, especially for ReflectionCubeMaps,

		///// which still looks okay in most cases and only adds some bandwidth

		///// overhead and 1 or even zero extra (because all we want might be the

		///// reflection cube map anyway) pixel shader instructions.

		///// </summary>

		//Reflection = 4 * 1024 * 1024,

		#endregion



		#region ShadowMapping

		/// <summary>

		/// Is this a shader to generate a shadow map? While the shader itself

		/// might not be very complex (we just need to render a depth map from

		/// the given light position), the implications on the engine are huge!

		/// First of all we need to render the whole scene from the light

		/// perspective into a render target and then use that for the

		/// UseShadowMap shader, which should be added dynamically to all existing

		/// shaders to make shadow mapping even work (or alternatively if the

		/// bandwidth allows this, we could render a extra pass on top of the

		/// final output lighten/darken up things). And finally we need to provide

		/// fallbacks for platforms that do not support shadow mapping at all

		/// each object if the performance allows us to do so (if not, use fake

		/// shadow blobs) and then display all these stencil or fake shadows

		/// instead of using a real shadow mapping algorithm.

		/// </summary>

		GenerateShadowMap = 8 * 1024 * 1024,



		/// <summary>

		/// This is the counterpart for GenerateShadowMap. The generated shadow

		/// map (or if fallbacks were used, the generated stencil shadows or

		/// shadow blobs) will be shown here. There are two ways the shadow map

		/// can be applied: 1. through an extra pass with a shader just using

		/// this flag, but this adds significant bandwidth and especially vertex

		/// computation overhead (we need to render the whole scene again) or 2.

		/// by just adding this flag to all the existing shaders in the scene,

		/// which only adds a single instructions to each pixel for the shadow

		/// mapping usually (can be more for more complex comparisons, but those

		/// should be done at the vertex level anyway). The second way is much

		/// faster and more desirable, but a lot harder to do for the engine,

		/// which should not matter for games however (because either you use

		/// shadow mapping in your game for a specific platform or not, only in

		/// unit tests you might want an extra pass to tweak the shadows).

		/// </summary>

		UseShadowMap = 16 * 1024 * 1024,

		#endregion



		#region PreScreen

		//Note: Removed, not longer used, we only use a sky dome right now.

		///// <summary>

		///// The sky needs to be rendered before everything else, which we call

		///// PreScreen shaders in the engine (other stuff can be done before

		///// rendering as well, but the sky makes the most sense here). This

		///// uses a cube map for the sky and will render it to the background

		///// (RenderLayer.Background) without depth buffer enabled. Everything

		///// else that will be rendered will be on top!

		///// </summary>

		//SkyCubeMapping = 32 * 1024 * 1024,

		#endregion



		#region PostScreen

		/// <summary>

		/// Use high dynamic range for the post screen calculations. This means

		/// the whole rendering happens into a render target that can do HDR

		/// and then the post screen shaders will apply tone mapping after

		/// all the effects are done to display the final result on the screen.

		/// Obviously this is not only slow on most mobile platform, but almost

		/// always not even supported, thus dynamic tone mapping is a thing for

		/// PC and consoles, but in the future some mobile platforms might have

		/// enough support and speed to do this (maybe not full scale, but for

		/// some stuff).

		/// </summary>

		PostScreenHDR = 64 * 1024 * 1024,



		/// <summary>

		/// Blur the post screen. Will just make everything blurry depending on

		/// how much pixel instructions and passes we can use for this (this is

		/// not a cheap effect and thus has to be ignored like all other post

		/// screen shaders on low quality mobile platforms).

		/// <para></para>

		/// Add fake HDR and glow effects to the scene by blurring it down and

		/// adding all bright spots to the final screen on top. This way we get

		/// a nice glow around all bright objects. This has similar impact on

		/// performance as Blur, but we can do some extra optimizations here.

		/// Still the main problem is the fill rate, to use this effect we not

		/// only need to calculate all the blur texture targets, but we also need

		/// to apply the glow to the final image, which costs at least 2 extra

		/// instructions (more if the glow is dynamic) for each pixel on the

		/// screen plus all the overhead with the render to texture issues.

		/// <para></para>

		/// Radial blur effect for fast moving games like RocketCommander or

		/// the RacingGame. I like it :) Might however not be suitable to every

		/// game. Main advantage here is that we can just reuse our last render

		/// target and go from there, this is much faster than Blur or Glow, but

		/// we still need a render target thus we still have that overhead.

		/// <para></para>

		/// Radial zoom is even crazier than just blurring the borders, we also

		/// zoom into the screen giving the impression of motion blur. This is

		/// again the same cheap effect as RadialBlur (also used in

		/// RocketCommander and RacingGame btw). It can look very cool and even

		/// has been used similarity in movies like Pitch Black, but when rotating

		/// around the whole illusion gets destroyed and for still pictures it is

		/// also not usable. Real per pixel motion blur is very hard however.

		/// </summary>

		PostScreenBlurOrGlow = 128 * 1024 * 1024,



		/// <summary>

		/// Color adjustment shader. Should mainly be used for unit testing and

		/// tweaking, not in the final game. Textures should already be tweaked by

		/// the artists to fit the final color and even if that was not done, we

		/// have a content system and can easily recolor all textures instead of

		/// doing this expensive operation at runtime! Sometimes we might want to

		/// change the mood of the scene however or we just want to color level

		/// parts differently. Then use this shader to recolor the whole scene and

		/// final output. On slower platforms this must be ignored most likely

		/// (so recoloring textures works better there).

		/// <para></para>

		/// PostScreenContrast:

		/// Similar to ColorAdjust Contrast should have been added to the

		/// textures already by the artists, but sometimes we might want to change

		/// the contrast dynamically for effects, menus or more dramatic scenes.

		/// This has a high overhead like ColorAdjust for a pretty simple effect.

		/// <para></para>

		/// PostScreenDarken:

		/// Darken the whole screen down. We don't need a shader for this,

		/// it can also be done with an overlay texture (even without any shaders

		/// at all). That still has the same pixel fill rate overhead however!

		/// On slower platforms use this with care, it is better to provide

		/// special code and only darken parts of the screen (e.g. if the menu

		/// is in the center, but you can see the game in the background, only

		/// darken the left and right sides that the user can see, not the whole

		/// screen).

		/// <para></para>

		/// PostScreenDesaturate:

		/// Desaturate the whole screen (same tips as for Darken apply here).

		/// This shader is really simple (even when calculating 0.3 * R +

		/// 0.59 * G + 0.11 * B), but we still have the same overhead as for all

		/// post screen shaders here (render target, fill rate bound), which

		/// can be optimized by only applying this post screen shader to smaller

		/// parts of the screen or by using different textures.

		/// <para></para>

		/// Please note that most PostScreen shaders we can combined, it makes no

		/// sense to apply different post screen shaders one after another if we

		/// can all do it in the same shader and highly optimize it there :)

		/// </summary>

		PostScreenColorAdjust = 256 * 1024 * 1024,

		//Unused:

		///// <summary>

		///// A toon shader will make look all edges much more sharp by adding

		///// black borders to them and then it will also simplify all colors

		///// giving the final screen a much more cartoonish like look. Has

		///// significant pixel and bandwidth overhead however. Can sometimes be

		///// faked with special geometry and by providing textures already in

		///// a cartoonish look, maybe only adding borders if the platform is

		///// fast enough for that.

		///// <para></para>

		///// PostScreenEdgeDetect:

		///// Edge detection shader, which is the basis of the Toon post screen

		///// shader. This will go through all pixels and try to find edges by

		///// comparing neighboring pixels (has obviously a high pixel fill rate

		///// impact). Then we can display those edges or do other things.

		///// </summary>

		//PostScreenToon = 512 * 1024 * 1024,

		//Unused:

		///// <summary>

		///// PostScreenRain: Post screen rain effect artists won't like, but it is

		///// cheap and easy to enable.

		///// <para></para>

		///// PostScreenSnow: Post screen snow effect artists won't like, but it is

		///// cheap and easy to enable.

		///// <para></para>

		///// PostScreenThermalView:

		///// Fake thermal view by applying a thermal view texture to each pixel in

		///// the scene (after gray scaling each pixel). Looks wrong, but still is

		///// a fun effect. More advanced thermal view shaders could have extra

		///// heat map textures for each object, use the depth or do other crazy

		///// things, but that is not supported right now.

		///// <para></para>

		///// PostScreenWobble:

		///// Simple wobble effect, has almost no overhead on the pixel shader, but

		///// needs a render target, thus not easily possible on mobile platforms.

		///// <para></para>

		///// PostScreenMenu:

		///// Menu post screen shader for special effects in the menu like

		///// distortions, color corrections, wobbling, water surface and other

		///// things.

		///// <para></para>

		///// Note: PostScreenMotionBlur: Per pixel motion blur, very hard to

		///// implement correctly.

		///// </summary>

		//PostScreenEffects = 1024 * 1024 * 1024,

		#endregion

	}

}