PB 6.00 - Shader documentation
Posted: Wed Jun 29, 2022 11:35 am
The documentation concerning the new 3D functions was not finished at the time of the translation of the doc, it contains errors and gaps
here is an update of the documentation about the shader + description of the predefined shader
I will give some examples of use later
___________________________________________________________________________________________
- CreateShader
enumeration of predefined shaders has no place here but in CreateShaderMaterial
note:
Shaders usually need to receive parameters to work:
2 functions allow to pass these parameters:
- MaterialShaderAutoParameter (automatic parameter)
- MaterialShaderParameter (shader parameter)
PureBasic also allows to set these parameters directly in the shader programs by adding at the end of the 'uniform' declaration line: "//" followed by either:
- the auto parameter number preceded by a "+" (cf. 'ParameterType' constants of the MaterialShaderAutoParameter function)
note: I will provide later a shader editor to simplify the assignment of these numbers
- one or more values (separated by a space) corresponding to the shader parameter (MaterialShaderParameter)
example:
uniform vec4 camera_pos;//+76 <- automatic parameter #PB_Shader_CameraPosition
uniform vec4 fog_params;//+31 <- automatic parameter #PB_Shader_FogParams
uniform vec3 speed;//0.5 1 0 <- shader parameter 'speed'
uniform sampler2D diffuseMap;//1 <- shader parameter texture number
___________________________________________________________________________________________
- MaterialShaderAutoParameter
description :
the automatic parameters correspond to the parameters of the 3D engine (positions of the camera, lights, color of the material, fog...)
this function allows to make the link between the 'uniform' variable of the shader and these parameters
example:
MaterialShaderAutoParameter(#Material, #PB_Shader_Fragment, #PB_Shader_CameraPosition, "camerapos", 0)
list of automatic parameters:
https://www.ogre3d.org/docs/manual18/ma ... d_005fauto
____________________________________________________________________________________________
- MaterialShaderParameter
description :
this function allows to set specific parameters to the shader
example:
MaterialShaderParameter(#Material, #PB_Shader_Fragment, "bumpy", #PB_Shader_Float, 0.5,0,0,0)
____________________________________________________________________________________________
CreateShaderMaterial
the ShaderID field must contain either
- the ID of a shader previously created with CreateShader
- the ID of a predefined shader:
#PB_Material_ColorShader
#PB_Material_PerpixelShader
#PB_Material_BumpShader
#PB_Material_SkyShader
#PB_Material_WaterShader
#PB_Material_WaterShaderRTT
#PB_Material_OceanShader
#PB_Material_PointSpriteSphereShader
#PB_MaterialShader_CubicEnvShader <- new
#PB_MaterialShader_CubicEnvBumpShader <- new
___________________________________________________________________________________________
___________________________________________________________________________________________
description of the predefined shaders:
___________________________________________________________________________________________
#PB_Material_ColorShader
Effect: uniform color in 'perpixel'.
texture(s) : none
MaterialShaderParameter : none
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor|#PB_Material_DiffuseColor, color)
- MaterialShininess(#Material, Shininess , SpecularColor)
- AmbiantColor
- Fog
- ScaleMaterial / ScrollMaterial / RotateMaterial
___________________________________________________________________________________________
#PB_Material_PerpixelShader
Effect: material in 'perpixel'
texture(s) :
- 0: sampler2D color
MaterialShaderParameter : none
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor|#PB_Material_DiffuseColor, color)
- MaterialShininess(#Material, Shininess , SpecularColor)
- LightAttenuation
- AmbiantColor
- Fog
- ScaleMaterial / ScrollMaterial / RotateMaterial
___________________________________________________________________________________________
#PB_Material_BumpShader
Effect: material with relief
texture(s) :
- 0: sampler2D color
- 1: sampler2D normal
MaterialShaderParameter :
#PB_Shader_Fragment
- float bumpy - default value: 1 (relief amplitude)
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor|#PB_Material_DiffuseColor, color)
- MaterialShininess(#Material, Shininess , SpecularColor)
- LightAttenuation
- AmbiantColor
- Fog
- ScaleMaterial / ScrollMaterial / RotateMaterial
remark(s):
- the tangents must be defined (use'BuildMeshTangent')
___________________________________________________________________________________________
#PB_Material_SkyShader
Effect: displays a sky with clouds and sun
texture(s) :
- 0: uniform sampler2D color (clouds)
MaterialShaderParameter :
#PB_Shader_Fragment
- vec3 speed - default value: 10 0 0 (speed of clouds (X Z))
- float height - default value: 200 (height of the 1st cloud layer)
- int layer - default value: 2 (number of additional cloud layers)
- float scale - default value: 4000 (texture scale)
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor, couleur): couleur du ciel soleil au zenith
- SetMaterialColor(#Material, #PB_Material_DiffuseColor, couleur): couleur du ciel soleil a l'horizon
- Fog
___________________________________________________________________________________________
#PB_Material_WaterShader
Effect : allows you to display a water surface
texture(s) :
- 0: sampler2D normal
MaterialShaderParameter :
#PB_Shader_Fragment
- float scale - default value: 0.1 (échelle de la texture)
- float height - default value: 1 (hauteur des vagues)
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_DiffuseColor, couleur): couleur de l'eau (Alpha: opacité)
- SetMaterialColor(#Material, #PB_Material_SpecularColor, couleur): couleur du reflet du ciel
- Fog
___________________________________________________________________________________________
#PB_Material_WaterShaderRTT
Effect : permet d'afficher une surface d'eau avec reflet (via RTT)
texture(s) :
- 0 : sampler2D normal
- 1 : sampler2D RTT (render to texture)
MaterialShaderParameter : none
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_DiffuseColor, couleur): couleur de l'eau (Alpha: opacité)
- Fog
- ScaleMaterial / ScrollMaterial / RotateMaterial
___________________________________________________________________________________________
#PB_Material_OceanShader
Effect : allows to display a water surface with waves
texture(s) :
- 0: sampler2D normal
- 1: sampler2D color (foam)
MaterialShaderParameter :
#PB_Shader_Vertex
- float wavebig - default value: 0.5 (wave amplitude)
- float swell - default value: 0.5 (swell amplitude)
#PB_Shader_Fragment
- float wavelittle - default value: 0.5 (amplitude of "small" waves)
- float foam - default value: 0.5 (foam)
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor, color): water color
- SetMaterialColor(#Material, #PB_Material_DiffuseColor, color): color of the sky reflection
- Fog
remark(s):
- the alpha value of the texture 'normal' contains the height of the wave
___________________________________________________________________________________________
#PB_Material_PointSpriteSphereShader
Effect: displays spheres at the vertices of the mesh
texture(s) : none
MaterialShaderParameter : none
Taking into account :
- SetMaterialColor(#Material, #PB_Material_AmbientColor|#PB_Material_DiffuseColor, color)
- MaterialShininess(#Material, Shininess , SpecularColor)
- AmbientColor
- Fog
remark(s):
- the material must be of type PointSprite : SetMaterialAttribute(0,#PB_Material_PointSprite,1)
- the mesh must be of type PointList : CreateMesh(#Mesh,#PB_Mesh_PointList)
- the radius of the sphere is defined by the texture coordinate U
- the color of the sphere is defined by the vertex color
example: MeshVertex(posX, posY, posZ, 10, 0,RGB(255,0,0))
_______________________________________________________________________________________
#PB_MaterialShader_CubicEnv
Effect: reflection via cubic texture
texture(s) :
- 0: samplerCube cubemap
- 1: uniform sampler2D color
MaterialShaderParameter :
#PB_Shader_Fragment
- float glossy - default value : 0.5 ( reflect intensity)
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor|#PB_Material_DiffuseColor, color)
- AmbiantColor
- Fog
- ScaleMaterial / ScrollMaterial / RotateMaterial
remark(s) :
- cubic textures must be 'clamped': SetMaterialAttribute(#texture, #PB_Material_TAM, #PB_Material_ClampTAM)
___________________________________________________________________________________________
#PB_MaterialShader_CubicEnvBump
Effect: reflection via cubic texture with relief
texture(s) :
- 0: samplerCube cubemap
- 1: sampler2D color
- 2: sampler2D normal
MaterialShaderParameter :
#PB_Shader_Fragment
- float glossy - default value : 0.5 (reflect intensity)
- float bumpy - default value : 1 (relief amplitude)
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor|#PB_Material_DiffuseColor, color)
- MaterialShininess(#Material, Shininess , SpecularColor)
- AmbiantColor
- Fog
- ScaleMaterial / ScrollMaterial / RotateMaterial
remark(s) :
- cubic textures must be 'clamped' : SetMaterialAttribute(#texture, #PB_Material_TAM, #PB_Material_ClampTAM)
- the tangents must be defined (use'BuildMeshTangent')
here is an update of the documentation about the shader + description of the predefined shader
I will give some examples of use later
___________________________________________________________________________________________
- CreateShader
enumeration of predefined shaders has no place here but in CreateShaderMaterial
note:
Shaders usually need to receive parameters to work:
2 functions allow to pass these parameters:
- MaterialShaderAutoParameter (automatic parameter)
- MaterialShaderParameter (shader parameter)
PureBasic also allows to set these parameters directly in the shader programs by adding at the end of the 'uniform' declaration line: "//" followed by either:
- the auto parameter number preceded by a "+" (cf. 'ParameterType' constants of the MaterialShaderAutoParameter function)
note: I will provide later a shader editor to simplify the assignment of these numbers
- one or more values (separated by a space) corresponding to the shader parameter (MaterialShaderParameter)
example:
uniform vec4 camera_pos;//+76 <- automatic parameter #PB_Shader_CameraPosition
uniform vec4 fog_params;//+31 <- automatic parameter #PB_Shader_FogParams
uniform vec3 speed;//0.5 1 0 <- shader parameter 'speed'
uniform sampler2D diffuseMap;//1 <- shader parameter texture number
___________________________________________________________________________________________
- MaterialShaderAutoParameter
description :
the automatic parameters correspond to the parameters of the 3D engine (positions of the camera, lights, color of the material, fog...)
this function allows to make the link between the 'uniform' variable of the shader and these parameters
example:
MaterialShaderAutoParameter(#Material, #PB_Shader_Fragment, #PB_Shader_CameraPosition, "camerapos", 0)
list of automatic parameters:
https://www.ogre3d.org/docs/manual18/ma ... d_005fauto
____________________________________________________________________________________________
- MaterialShaderParameter
description :
this function allows to set specific parameters to the shader
example:
MaterialShaderParameter(#Material, #PB_Shader_Fragment, "bumpy", #PB_Shader_Float, 0.5,0,0,0)
____________________________________________________________________________________________
CreateShaderMaterial
the ShaderID field must contain either
- the ID of a shader previously created with CreateShader
- the ID of a predefined shader:
#PB_Material_ColorShader
#PB_Material_PerpixelShader
#PB_Material_BumpShader
#PB_Material_SkyShader
#PB_Material_WaterShader
#PB_Material_WaterShaderRTT
#PB_Material_OceanShader
#PB_Material_PointSpriteSphereShader
#PB_MaterialShader_CubicEnvShader <- new
#PB_MaterialShader_CubicEnvBumpShader <- new
___________________________________________________________________________________________
___________________________________________________________________________________________
description of the predefined shaders:
___________________________________________________________________________________________
#PB_Material_ColorShader
Effect: uniform color in 'perpixel'.
texture(s) : none
MaterialShaderParameter : none
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor|#PB_Material_DiffuseColor, color)
- MaterialShininess(#Material, Shininess , SpecularColor)
- AmbiantColor
- Fog
- ScaleMaterial / ScrollMaterial / RotateMaterial
___________________________________________________________________________________________
#PB_Material_PerpixelShader
Effect: material in 'perpixel'
texture(s) :
- 0: sampler2D color
MaterialShaderParameter : none
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor|#PB_Material_DiffuseColor, color)
- MaterialShininess(#Material, Shininess , SpecularColor)
- LightAttenuation
- AmbiantColor
- Fog
- ScaleMaterial / ScrollMaterial / RotateMaterial
___________________________________________________________________________________________
#PB_Material_BumpShader
Effect: material with relief
texture(s) :
- 0: sampler2D color
- 1: sampler2D normal
MaterialShaderParameter :
#PB_Shader_Fragment
- float bumpy - default value: 1 (relief amplitude)
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor|#PB_Material_DiffuseColor, color)
- MaterialShininess(#Material, Shininess , SpecularColor)
- LightAttenuation
- AmbiantColor
- Fog
- ScaleMaterial / ScrollMaterial / RotateMaterial
remark(s):
- the tangents must be defined (use'BuildMeshTangent')
___________________________________________________________________________________________
#PB_Material_SkyShader
Effect: displays a sky with clouds and sun
texture(s) :
- 0: uniform sampler2D color (clouds)
MaterialShaderParameter :
#PB_Shader_Fragment
- vec3 speed - default value: 10 0 0 (speed of clouds (X Z))
- float height - default value: 200 (height of the 1st cloud layer)
- int layer - default value: 2 (number of additional cloud layers)
- float scale - default value: 4000 (texture scale)
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor, couleur): couleur du ciel soleil au zenith
- SetMaterialColor(#Material, #PB_Material_DiffuseColor, couleur): couleur du ciel soleil a l'horizon
- Fog
___________________________________________________________________________________________
#PB_Material_WaterShader
Effect : allows you to display a water surface
texture(s) :
- 0: sampler2D normal
MaterialShaderParameter :
#PB_Shader_Fragment
- float scale - default value: 0.1 (échelle de la texture)
- float height - default value: 1 (hauteur des vagues)
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_DiffuseColor, couleur): couleur de l'eau (Alpha: opacité)
- SetMaterialColor(#Material, #PB_Material_SpecularColor, couleur): couleur du reflet du ciel
- Fog
___________________________________________________________________________________________
#PB_Material_WaterShaderRTT
Effect : permet d'afficher une surface d'eau avec reflet (via RTT)
texture(s) :
- 0 : sampler2D normal
- 1 : sampler2D RTT (render to texture)
MaterialShaderParameter : none
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_DiffuseColor, couleur): couleur de l'eau (Alpha: opacité)
- Fog
- ScaleMaterial / ScrollMaterial / RotateMaterial
___________________________________________________________________________________________
#PB_Material_OceanShader
Effect : allows to display a water surface with waves
texture(s) :
- 0: sampler2D normal
- 1: sampler2D color (foam)
MaterialShaderParameter :
#PB_Shader_Vertex
- float wavebig - default value: 0.5 (wave amplitude)
- float swell - default value: 0.5 (swell amplitude)
#PB_Shader_Fragment
- float wavelittle - default value: 0.5 (amplitude of "small" waves)
- float foam - default value: 0.5 (foam)
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor, color): water color
- SetMaterialColor(#Material, #PB_Material_DiffuseColor, color): color of the sky reflection
- Fog
remark(s):
- the alpha value of the texture 'normal' contains the height of the wave
___________________________________________________________________________________________
#PB_Material_PointSpriteSphereShader
Effect: displays spheres at the vertices of the mesh
texture(s) : none
MaterialShaderParameter : none
Taking into account :
- SetMaterialColor(#Material, #PB_Material_AmbientColor|#PB_Material_DiffuseColor, color)
- MaterialShininess(#Material, Shininess , SpecularColor)
- AmbientColor
- Fog
remark(s):
- the material must be of type PointSprite : SetMaterialAttribute(0,#PB_Material_PointSprite,1)
- the mesh must be of type PointList : CreateMesh(#Mesh,#PB_Mesh_PointList)
- the radius of the sphere is defined by the texture coordinate U
- the color of the sphere is defined by the vertex color
example: MeshVertex(posX, posY, posZ, 10, 0,RGB(255,0,0))
_______________________________________________________________________________________
#PB_MaterialShader_CubicEnv
Effect: reflection via cubic texture
texture(s) :
- 0: samplerCube cubemap
- 1: uniform sampler2D color
MaterialShaderParameter :
#PB_Shader_Fragment
- float glossy - default value : 0.5 ( reflect intensity)
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor|#PB_Material_DiffuseColor, color)
- AmbiantColor
- Fog
- ScaleMaterial / ScrollMaterial / RotateMaterial
remark(s) :
- cubic textures must be 'clamped': SetMaterialAttribute(#texture, #PB_Material_TAM, #PB_Material_ClampTAM)
___________________________________________________________________________________________
#PB_MaterialShader_CubicEnvBump
Effect: reflection via cubic texture with relief
texture(s) :
- 0: samplerCube cubemap
- 1: sampler2D color
- 2: sampler2D normal
MaterialShaderParameter :
#PB_Shader_Fragment
- float glossy - default value : 0.5 (reflect intensity)
- float bumpy - default value : 1 (relief amplitude)
Taking into account of :
- SetMaterialColor(#Material, #PB_Material_AmbientColor|#PB_Material_DiffuseColor, color)
- MaterialShininess(#Material, Shininess , SpecularColor)
- AmbiantColor
- Fog
- ScaleMaterial / ScrollMaterial / RotateMaterial
remark(s) :
- cubic textures must be 'clamped' : SetMaterialAttribute(#texture, #PB_Material_TAM, #PB_Material_ClampTAM)
- the tangents must be defined (use'BuildMeshTangent')
