1. We're looking for feedback on Unity Starter Kits! Let us know what you’d like.
    Dismiss Notice
  2. Unity 2017.2 beta is now available for download.
    Dismiss Notice
  3. Unity 2017.1 is now released.
    Dismiss Notice
  4. Introducing the Unity Essentials Packs! Find out more.
    Dismiss Notice
  5. Check out all the fixes for 5.6 on the patch releases page.
    Dismiss Notice
  6. Help us improve the editor usability and artist workflows. Join our discussion to provide your feedback.
    Dismiss Notice

Shaderlab Documentation Requests

Discussion in 'Shaders' started by Tim-C, Sep 1, 2012.

  1. Tim-C

    Tim-C

    Unity Technologies

    Joined:
    Feb 6, 2010
    Posts:
    1,909
    Post any documentation requests here. Please keep this thread just to requests and not discussions. Any not request posts will be removed (this is just to make it easier for us for when we look through the thread).
     
  2. mgear

    mgear

    Joined:
    Aug 3, 2010
    Posts:
    3,780
    Some random ideas.. (from someone who hasnt done any shader stuff before unity..)

    1. Easy to find list of all the possible keywords, functions etc. that are supported in unity, as in: http://http.developer.nvidia.com/Cg/index_stdlib.html
    2. Also some reference grid (or color code on the page) would indicate if it works on indie or pro.. (color code would be useful in other documents also.. now the text "requires pro" is just somewhere inside the page/text..)
    3. Search box for the documentation (something that actually works.. with autocomplete etc. or just add google site search form..)
    4. Info how to convert shaders from other languages/engines (you want people to come to unity..make it easy for them)
    5. And this kind of info: http://forum.unity3d.com/threads/66271-Nvidia-ShaderFx-standart-matrices-equavelant-in-unity
    6. Update shader FAQ (with real top 30 questions that are always coming up..)
    7. More example sources.. (maybe you could even pick your shader language/target(?) to view the code, just like in scripting docs you pick js/c#/boo..)
    8. Images on the documentation, what is world reflection vector etc.? (draw the line how it works / what it means, or put a link to wikipedia or other sites..)
    9. CHM help file would be perfect.. (see example: MaxScript .chm documentation from 3ds max 2010 vs 2012 online help version.. the new (search) system is horrible)
    10. Error code database with atleast some short human readable explanations..
     
  3. BIG-BUG

    BIG-BUG

    Joined:
    Mar 29, 2009
    Posts:
    451
    Cloned and updated post from the documenation wish list topic:

    -A Shader Command Reference (incl. predefined macros, variables and compiler pragmas) would be really helpful. (incl. remarks if a specific command is not available on certain devices). This should also include working CG commands - even if those commands can be found elsewhere a compilated documentation is by far better then searching the internet.
    -For each type of shader (fragment, vertex, surface) there should be a description in table form which in- and output values are possible / obligatory
    -A differentiation between the possible techniques( fixed function, fragment, vertex, surface ) and when to use what and how interaction with Unity lights, Beast lightmaps and light probes work.
    -Better and more detailed description for Surface Shaders. How does multi-pass rendering work? Which of the regular shader commands like Blend, ZWrite, Lighting work? Is it possible to write a depth value? How to combine surface shader with regular ones?
     
  4. hippocoder

    hippocoder

    Digital Ape Moderator

    Joined:
    Apr 11, 2010
    Posts:
    19,157
    In depth explanation of light probes and shaders and lots and lots of mobile friendly tips and snippets for cg. I feel quite strongly I'd like to stay in cg as it is cross platform.

    A list of fast and slow common shader issues in unity. Making our own shaders is the aim of documentation so I want to make them faster and higher performing. Documentation important for speed because trial and error will get you a slow but working shader hacking unity stuff. We don't want that.
     
    Heisenbug likes this.
  5. foxter888

    foxter888

    Joined:
    May 3, 2010
    Posts:
    530
    i wonder since unity started doing curves for the shuriken particle system they started to implement it into other systems such as the mechanim and so on,
    so one question would be what if they made something similar to strumpy implementing the curves and the behavior tree from mechanim? i wonder if they would do that for their AI and new gui? lol then again this probably be out of context lol.
     
  6. Farfarer

    Farfarer

    Joined:
    Aug 17, 2010
    Posts:
    2,249
    A list of all the keywords/defines that Unity uses - and descriptions of where/when - would be really handy.
     
  7. Lulucifer

    Lulucifer

    Joined:
    Jul 8, 2012
    Posts:
    334
    I want a clear full step of how lights is picked and setted to such as _WorldSpaceLightPos0 and unity_LightPosition before one object is going to be rendered
     
  8. Farfarer

    Farfarer

    Joined:
    Aug 17, 2010
    Posts:
    2,249
  9. Lulucifer

    Lulucifer

    Joined:
    Jul 8, 2012
    Posts:
    334
    It is,but not clear enough. I wanna to see the 'if else' code which we dont know,it should be some of unity's source code, i guess
     
  10. ywq

    ywq

    Joined:
    Aug 22, 2012
    Posts:
    15
    More document for UnityCG.cginc,AutoLight.cginc,Lighting.cginc and etc.
    I can guess it from function name and its description,but I can't guess the parameters mean.
     
  11. FernandoRibeiro

    FernandoRibeiro

    Joined:
    Sep 23, 2009
    Posts:
    1,362
    Documentation about DirectX 11 hair shader would be great :) I read Nvidia was involved in the solution, not sure if it can be public thought.
     
  12. Zergling103

    Zergling103

    Joined:
    Aug 16, 2011
    Posts:
    241
    Can you please post the surface shader examples page included in the docs for 3.5? Thanks.
     
  13. 1337GameDev

    1337GameDev

    Joined:
    Oct 31, 2011
    Posts:
    53
    --------More documentation on grabpass, and its uses. What can you all do with the texture that is grabbed, and how to use this in a cg program, besides just shaderlab and setTexture.

    -------Common shader functions and how do do them/ set them up.
    -------How to get pixel data from grab pass, texture, or manipulating pixel data
     
  14. Lulucifer

    Lulucifer

    Joined:
    Jul 8, 2012
    Posts:
    334
    It is not for a document,but i think it is the most proper place.
    how long should we wait to use Nvidia's NSight to debug shader in unity,any way can we do that
    or any genius makes a tool like that
     
  15. sgoodrow

    sgoodrow

    Joined:
    Sep 28, 2012
    Posts:
    150
    Document how to modify/use replacement shaders for the built-in CameraDepth-Texture shaders.
     
  16. Manul

    Manul

    Joined:
    Nov 30, 2012
    Posts:
    18
    complete! documentation of all built-in graphics related functionality
    - the include files
    - precompiled macros
    - shader variables set by unity
    - exact form of the projection matrices used by standard cameras and shadowmap cameras

    Even if it will change often. I'd rather adapt code to documented changes than having big holes in the documentation.

    Right now our best hope for an answer is a direct question to aras or someone else in the know. They are doing a great job, but obviously can't answer any single request. Having a complete documentation would reduce the number of questions to answer and open up space for customization by the community...
     
  17. Manul

    Manul

    Joined:
    Nov 30, 2012
    Posts:
    18
    Documentation for

    float clamped = max(o.pos.z, o.pos.w*UNITY_NEAR_CLIP_VALUE);
    o.pos.z = lerp(o.pos.z, clamped, unity_LightShadowBias.y);

    in #define TRANSFER_SHADOW_CASTER(o) in UnityCG.cginc

    Without knowing the exact setup of the projection matrix I have to guess what the value of o.pos.w is.
    unity_LightShadowBias seems to be an undocumented variable. The x-component apparently is the light.bias, but what is in the y-component?
     
  18. porglezomp

    porglezomp

    Joined:
    Aug 21, 2012
    Posts:
    40
    I'd like the documentation on the custom Z values mentioned in the 4.2 release notes.
     
  19. NumbSeven

    NumbSeven

    Joined:
    Jan 10, 2013
    Posts:
    1
    看不懂
     
  20. cician

    cician

    Joined:
    Dec 10, 2012
    Posts:
    230
    Documentation doesn't mention you can add [HideInInspector] before property in a shader.
    Are there other options, like property drawers?
     
  21. laurentlavigne

    laurentlavigne

    Joined:
    Aug 16, 2012
    Posts:
    1,099
    A FAQ!
    For example: how do I make a shader lightmap only?
    and in EVERY example, show CG, surface shader, shaderlab legacy so we can learn by comparison.
     
  22. tanoshimi

    tanoshimi

    Joined:
    May 21, 2013
    Posts:
    278
    Explanation of "Dependency" shaders. e.g.
    Dependency "Details0"
    Dependency "Details1"
    Dependency "Details2"
    Dependency "Tree0"
    Dependency "BaseMapShader"
    Dependency "AddPassShader"
     
  23. imaginaryhuman

    imaginaryhuman

    Joined:
    Mar 21, 2010
    Posts:
    5,315
    How about a full list of the performance of every shader on a variety of platforms, so its easier to tell what is faster/slower.
     
  24. ninjapretzel

    ninjapretzel

    Joined:
    Jul 19, 2011
    Posts:
    14

    I would like to put another request towards #1 here.
    It's been over a year since that post was made, and there is still no documentation in Unity on what structs and functions are available in shaderlab..

    Something like this, but for shaderlab.
    http://en.wikibooks.org/wiki/GLSL_Programming/Vector_and_Matrix_Operations
     
    Last edited: Jan 15, 2014
  25. cician

    cician

    Joined:
    Dec 10, 2012
    Posts:
    230
    Documentation should mention what space Surface Shader lighting function operates in. Even if in most cases you don't even need to know.
    Unity 5 seems to have changed it to world space and SurfaceOutput.Normal is transformed behind the scenes. I had to study compiled shader to understand what is happening.
     
  26. AironeneroTechnologies

    AironeneroTechnologies

    Joined:
    Nov 11, 2013
    Posts:
    130
    Also examples for texture combining in unity 4 and unity 5. Really, for beginners like me understanding how shader lab works is a bit complicated.
     
  27. TechnoCraft

    TechnoCraft

    Joined:
    Apr 6, 2012
    Posts:
    28
    Compute Shaders documentation. DirectCompute, CUDA, OpenCL are documented on official sites but simply copying the original code in a Compute Shader will not work. There are rules to how a compute shader should be written in Unity (what applies and what not). More detailed documentation on Unity specifics would be really helpfull. For example see ScrawkBlog about DirectCompute in Unity.
     
  28. cowlinator

    cowlinator

    Joined:
    Mar 15, 2012
    Posts:
    67
  29. bloomingdedalus

    bloomingdedalus

    Joined:
    Aug 13, 2012
    Posts:
    139
    Like you have a vertex and fragment tutorial in the documentation - a hull, domain, and geometry one would be awesome. I was fortunate to find a geometry shader example so I learned how to use that (novice level), but I can't find information on how to implement hull and domain functions.
     
    varfare and Emma-Ewert like this.
  30. Nanako

    Nanako

    Joined:
    Sep 24, 2014
    Posts:
    1,047
    put the source code of all the builtin shaders in the online documentation
     
    Ryan-Gatts likes this.
  31. Panpan2029

    Panpan2029

    Joined:
    Mar 13, 2015
    Posts:
    3
    The modification and change of shaders in Version 5. Like the sample of "Circles Mask" in the document does not work any more in Version 5.0.0f4
     
  32. Phantomx

    Phantomx

    Joined:
    Oct 30, 2012
    Posts:
    202
    Noisecrime likes this.
  33. Zicandar

    Zicandar

    Joined:
    Feb 10, 2014
    Posts:
    388
  34. Elecman

    Elecman

    Joined:
    May 5, 2011
    Posts:
    1,075
  35. varfare

    varfare

    Joined:
    Feb 12, 2013
    Posts:
    204
    Documentation is lacking information about using Unity 5 transparent shadows and Unity shadows in general. It would be really helpful if you would write down simple shadow-caster example somewhere in the docs.
     
  36. cowtrix

    cowtrix

    Joined:
    Oct 23, 2012
    Posts:
    231
  37. Baste

    Baste

    Joined:
    Jan 24, 2013
    Posts:
    2,272
    Reading through the Lambert lighting functions from Ligthing.cginc, it seems like how lighting is done has changed in a major way since Unity 4. The signature in Unity 4.6 is:

    Code (csharp):
    1. inline fixed4 LightingLambert (SurfaceOutput s, fixed3 lightDir, fixed atten)
    while in Unity 5 it is:

    Code (csharp):
    1. inline fixed4 LightingLambert (SurfaceOutput s, UnityGI gi)
    This way of implementing light also requires a Lighting<Name>_GI function which seems to create the UnityGI parameter. This is very different from how the docs work. So this stuff definitely needs an update.

    It also seems like surface shaders with transparency will break hard if legacy deferred lighting is used, and the Lighting<Name>_PrePass function isn't implemented. Not sure if that's me not understanding what has happened, or if it's a bug.
     
  38. Wurghi

    Wurghi

    Joined:
    Apr 11, 2013
    Posts:
    39
    give us information about the witchcraft behind the "fallback "Diffuse"" part at the end of a shader. Makes a big difference for some shaders that need depthwriting for example if you forget it.
     
  39. Ippokratis

    Ippokratis

    Joined:
    Oct 13, 2008
    Posts:
    1,442
    Please, fix StandardShaderGUI.cs line 203 to DetermineWorkflow( MaterialEditor.GetMaterialProperties(new Material[] { material }) ); so I do not have to do it manually every time I import the builtin shader source.
    Thanks.
     
  40. varfare

    varfare

    Joined:
    Feb 12, 2013
    Posts:
    204
  41. cician

    cician

    Joined:
    Dec 10, 2012
    Posts:
    230
    Information on multi-pass rendering order when writing plain - that is not "surface" - cg shaders with forward lighting.
    Does the engine guarantee any order like the following?
    • foreach object
    • foreach pass
    • foreach light
    or
    • foreach object
    • foreach light
    • foreach pass
     
  42. Farfarer

    Farfarer

    Joined:
    Aug 17, 2010
    Posts:
    2,249
    The objects are ordered by render queue of the shader for their material and then by distance to the camera (should be near-to-far for opaque/cutout and far-to-near for transparent).

    For forward rendering, the base pass is always rendered first - this includes the most important/influential directional light. If there are no directional lights then it just assumes a black light color. This also does all the vertex/sh/gi lighting.

    Then additive pass is drawn on top of that, once each for each extra pixel light up to the maximum specified... I'm not certain if they're ordered by importance/influence, though (although I suspect they are as the next 4 lights after that are rendered as vertex lighting in the base pass, and the next 9 lights after that are done as spherical harmonics... so there's a list of influence anyway).

    Passes within a shader are executed in the order they are written.
     
  43. cician

    cician

    Joined:
    Dec 10, 2012
    Posts:
    230
    Thanks @Farfarer, actually this page in the docs already covers most of it pretty well (yep, ordered by importance).
    What is missing for me is some info required for writing a multi-pass shader in forward mode.
    The problem rises when your passes are order dependent. Of course I'd rather avoid multi-pass shaders where I need just a few more than 64 instructions.
    In my two scenarios, the first is apparently the valid one, but since it's undocumented it may be just an implementation, and so it may change in future Unity versions.
    The second scenario would allow more optimizations, like reusing light attenuation and shadow penumbra between passes, but is clearly not valid.

    p.s. & off-topic: SH lighting is now done [partially] per pixel, so the vertex lights are now kinda worse visually than SH. It would be nice if Unity Technologies get rid of the vertex lights and use just SH instead, as long as they fix their SH code a bit (not that I'd do better, but there's clearly something off). I want forward+ or something. Snif...
     
  44. LustForLife

    LustForLife

    Joined:
    Jul 12, 2013
    Posts:
    1
    Hi!
    Where i can find new location of docs under "Things to know when writing Cg shaders", from this topic:
    http://forum.unity3d.com/threads/shaderlab-faq.19166/

    And where i can find more info about stuff from CGincludes. Looks like lot of work already done ;), but want have a list of content, at least.

    Thanks!
     
  45. Aras

    Aras

    Graphics Plumber Unity Technologies

    Joined:
    Nov 7, 2005
    Posts:
    4,522
    Check out sub-pages of the "writing vertex and fragment programs" documentation page.
     
  46. a_p_u_r_o

    a_p_u_r_o

    Joined:
    May 27, 2015
    Posts:
    16
    FAQ
    Q. What is the equivalent of gl_VertexID?
    A. SV_VertexID. -> http://docs.unity3d.com/Manual/SL-ShaderSemantics.html
    The shader translator will properly utilize gl_VertexID for OpenGL based platforms.
    Note: OpenGLES20 (GLES 2.0) based platforms usually do not support gl_VertexID.
     
  47. varfare

    varfare

    Joined:
    Feb 12, 2013
    Posts:
    204
    It's been few months now since Unity 5.0 and these are still not documented:
    - how to handle reflection probes inside CG shader
    - how to handle GI bounces inside CG shader

    Also:
    - how do you broadcast your own shadowmap so that all built-in and surface shaders sample it (force shadow-receiver pass for all objects?)
    - what variable stores light attenuation&range (Forward rendering pass)?
     
  48. Aras

    Aras

    Graphics Plumber Unity Technologies

    Joined:
    Nov 7, 2005
    Posts:
    4,522
    "Environment Reflection using World-Space Normals" example from http://docs.unity3d.com/Manual/SL-VertexFragmentShaderExamples.html almost gets you that -- that one is only for the default sky reflection, but I think if the pass has LightMode=ForwardAdd, then it will pick up actual reflection probes automatically too.
     
  49. varfare

    varfare

    Joined:
    Feb 12, 2013
    Posts:
    204
    Ohh. Thanks for the link. I have totally missed that.
     
  50. Horz

    Horz

    Joined:
    Nov 26, 2013
    Posts:
    159