class_docstr: Apply shading to a :class:`~vispy.visuals.mesh.MeshVisual` using the Phong reflection model.
  
  For convenience, a :class:`~vispy.visuals.mesh.MeshVisual` creates and
  embeds a shading filter when constructed with an explicit `shading`
  parameter, e.g. `mesh = MeshVisual(..., shading='smooth')`. The filter is
  then accessible as `mesh.shading_filter`.
  
  When attached manually to a :class:`~vispy.visuals.mesh.MeshVisual`, the
  shading filter should come after any other filter that modifies the base
  color to be shaded. See the examples below.
  
  Parameters
  ----------
  shading : str
      Shading mode: None, 'flat' or 'smooth'. If None, the shading is
      disabled.
  ambient_coefficient : str or tuple or Color
      Color and intensity of the ambient reflection coefficient (Ka).
  diffuse_coefficient : str or tuple or Color
      Color and intensity of the diffuse reflection coefficient (Kd).
  specular_coefficient : str or tuple or Color
      Color and intensity of the specular reflection coefficient (Ks).
  shininess : float
      The shininess controls the size of specular highlight. The higher, the
      more localized.  Must be greater than or equal to zero.
  light_dir : array_like
      Direction of the light. Assuming a directional light.
  ambient_light : str or tuple or Color
      Color and intensity of the ambient light.
  diffuse_light : str or tuple or Color
      Color and intensity of the diffuse light.
  specular_light : str or tuple or Color
      Color and intensity of the specular light.
  enabled : bool, default=True
      Whether the filter is enabled at creation time. This can be changed at
      run time with :obj:`~enabled`.
  
  Notes
  -----
  Under the Phong reflection model, the illumination `I` is computed as::
  
      I = I_ambient + mesh_color * I_diffuse + I_specular
  
  for each color channel independently.
  `mesh_color` is the color of the :class:`~vispy.visuals.mesh.MeshVisual`,
  possibly modified by the filters applied before this one.
  The ambient, diffuse and specular terms are defined as::
  
      I_ambient = Ka * Ia
      I_diffuse = Kd * Id * dot(L, N)
      I_specular = Ks * Is * dot(R, V) ** s
  
  with
  
  `L`
      the light direction, assuming a directional light,
  `N`
      the normal to the surface at the reflection point,
  `R`
      the direction of the reflection,
  `V`
      the direction to the viewer,
  `s`
      the shininess factor.
  
  The `Ka`, `Kd` and `Ks` coefficients are defined as an RGBA color. The RGB
  components define the color that the surface reflects, and the alpha
  component (A) defines the intensity/attenuation of the reflection. When
  applied in the per-channel illumation formulas above, the color component
  is multiplied by the intensity to obtain the final coefficient, e.g.
  `Kd = R * A` for the red channel.
  
  Similarly, the light intensities, `Ia`, `Id` and `Is`, are defined by RGBA
  colors, corresponding to the color of the light and its intensity.
  
  Examples
  --------
  Define the mesh data for a :class:`vispy.visuals.mesh.MeshVisual`:
  
  >>> # A triangle.
  >>> vertices = np.array([(0, 0, 0), (1, 1, 1), (0, 1, 0)], dtype=float)
  >>> faces = np.array([(0, 1, 2)], dtype=int)
  
  Let the :class:`vispy.visuals.mesh.MeshVisual` create and embed a shading
  filter:
  
  >>> mesh = MeshVisual(vertices, faces, shading='smooth')
  >>> # Configure the filter afterwards.
  >>> mesh.shading_filter.shininess = 64
  >>> mesh.shading_filter.specular_coefficient = 0.3
  
  Create the shading filter manually and attach it to a
  :class:`vispy.visuals.mesh.MeshVisual`:
  
  >>> # With the default shading parameters.
  >>> shading_filter = ShadingFilter()
  >>> mesh = MeshVisual(vertices, faces)
  >>> mesh.attach(shading_filter)
  
  The filter can be configured at creation time and at run time:
  
  >>> # Configure at creation time.
  >>> shading_filter = ShadingFilter(
  ...     # A shiny surface (small specular highlight).
  ...     shininess=250,
  ...     # A blue higlight, at half intensity.
  ...     specular_coefficient=(0, 0, 1, 0.5),
  ...     # Equivalent to `(0.7, 0.7, 0.7, 1.0)`.
  ...     diffuse_coefficient=0.7,
  ...     # Same as `(0.2, 0.3, 0.3, 1.0)`.
  ...     ambient_coefficient=(0.2, 0.3, 0.3),
  ... )
  >>> # Change the configuration at run time.
  >>> shading_filter.shininess = 64
  >>> shading_filter.specular_coefficient = 0.3
  
  Disable the filter temporarily:
  
  >>> # Turn off the shading.
  >>> shading_filter.enabled = False
  ... # Some time passes...
  >>> # Turn on the shading again.
  >>> shading_filter.enabled = True
  
  When using the :class:`WireframeFilter`, the wireframe is shaded only if
  the wireframe filter is attached before the shading filter:
  
  >>> shading_filter = ShadingFilter()
  >>> wireframe_filter = WireframeFilter()
  >>> # Option 1: Shade the wireframe.
  >>> mesh1 = MeshVisual(vertices, faces)
  >>> mesh1.attached(wireframe_filter)
  >>> mesh1.attached(shading_filter)
  >>> # Option 2: Do not shade the wireframe.
  >>> mesh2 = MeshVisual(vertices, faces)
  >>> mesh2.attached(shading_filter)
  >>> mesh2.attached(wireframe_filter)
  
  See also
  `examples/basics/scene/mesh_shading.py
  <https://github.com/vispy/vispy/blob/main/examples/basics/scene/mesh_shading.py>`_
  example script.
class_docstr_tok: ["Apply","shading","to","a",":","class",":","`","~vispy.visuals.mesh.MeshVisual","`","using","the","Phong","reflection","model",".","For","convenience",",","a",":","class",":","`","~vispy.visuals.mesh.MeshVisual","`","creates","and","embeds","a","shading","filter","when","constructed","with","an","explicit","`","shading","`","parameter",",","e.g",".","`","mesh","=","MeshVisual","(","...",",","shading='smooth","'",")","`",".","The","filter","is","then","accessible","as","`","mesh.shading_filter","`",".","When","attached","manually","to","a",":","class",":","`","~vispy.visuals.mesh.MeshVisual","`",",","the","shading","filter","should","come","after","any","other","filter","that","modifies","the","base","color","to","be","shaded",".","See","the","examples","below",".","Parameters","--","--","--","--","--","shading",":","str","Shading","mode",":","None",",","'flat","'","or","'smooth","'",".","If","None",",","the","shading","is","disabled",".","ambient_coefficient",":","str","or","tuple","or","Color","Color","and","intensity","of","the","ambient","reflection","coefficient","(","Ka",")",".","diffuse_coefficient",":","str","or","tuple","or","Color","Color","and","intensity","of","the","diffuse","reflection","coefficient","(","Kd",")",".","specular_coefficient",":","str","or","tuple","or","Color","Color","and","intensity","of","the","specular","reflection","coefficient","(","Ks",")",".","shininess",":","float","The","shininess","controls","the","size","of","specular","highlight",".","The","higher",",","the","more","localized",".","Must","be","greater","than","or","equal","to","zero",".","light_dir",":","array_like","Direction","of","the","light",".","Assuming","a","directional","light",".","ambient_light",":","str","or","tuple","or","Color","Color","and","intensity","of","the","ambient","light",".","diffuse_light",":","str","or","tuple","or","Color","Color","and","intensity","of","the","diffuse","light",".","specular_light",":","str","or","tuple","or","Color","Color","and","intensity","of","the","specular","light",".","enabled",":","bool",",","default=True","Whether","the","filter","is","enabled","at","creation","time",".","This","can","be","changed","at","run","time","with",":","obj",":","`","~enabled","`",".","Notes","--","--","-","Under","the","Phong","reflection","model",",","the","illumination","`","I","`","is","computed","as",":",":","I","=","I_ambient","+","mesh_color","*","I_diffuse","+","I_specular","for","each","color","channel","independently",".","`","mesh_color","`","is","the","color","of","the",":","class",":","`","~vispy.visuals.mesh.MeshVisual","`",",","possibly","modified","by","the","filters","applied","before","this","one",".","The","ambient",",","diffuse","and","specular","terms","are","defined","as",":",":","I_ambient","=","Ka","*","Ia","I_diffuse","=","Kd","*","Id","*","dot","(","L",",","N",")","I_specular","=","Ks","*","Is","*","dot","(","R",",","V",")","*","*","s","with","`","L","`","the","light","direction",",","assuming","a","directional","light",",","`","N","`","the","normal","to","the","surface","at","the","reflection","point",",","`","R","`","the","direction","of","the","reflection",",","`","V","`","the","direction","to","the","viewer",",","`","s","`","the","shininess","factor",".","The","`","Ka","`",",","`","Kd","`","and","`","Ks","`","coefficients","are","defined","as","an","RGBA","color",".","The","RGB","components","define","the","color","that","the","surface","reflects",",","and","the","alpha","component","(","A",")","defines","the","intensity\/attenuation","of","the","reflection",".","When","applied","in","the","per-channel","illumation","formulas","above",",","the","color","component","is","multiplied","by","the","intensity","to","obtain","the","final","coefficient",",","e.g",".","`","Kd","=","R","*","A","`","for","the","red","channel",".","Similarly",",","the","light","intensities",",","`","Ia","`",",","`","Id","`","and","`","Is","`",",","are","defined","by","RGBA","colors",",","corresponding","to","the","color","of","the","light","and","its","intensity",".","Examples","--","--","--","--","Define","the","mesh","data","for","a",":","class",":","`","vispy.visuals.mesh.MeshVisual","`",":",">",">",">","#","A","triangle",".",">",">",">","vertices","=","np.array","(","[","(","0",",","0",",","0",")",",","(","1",",","1",",","1",")",",","(","0",",","1",",","0",")","]",",","dtype=float",")",">",">",">","faces","=","np.array","(","[","(","0",",","1",",","2",")","]",",","dtype=int",")","Let","the",":","class",":","`","vispy.visuals.mesh.MeshVisual","`","create","and","embed","a","shading","filter",":",">",">",">","mesh","=","MeshVisual","(","vertices",",","faces",",","shading='smooth","'",")",">",">",">","#","Configure","the","filter","afterwards",".",">",">",">","mesh.shading_filter.shininess","=","64",">",">",">","mesh.shading_filter.specular_coefficient","=","0.3","Create","the","shading","filter","manually","and","attach","it","to","a",":","class",":","`","vispy.visuals.mesh.MeshVisual","`",":",">",">",">","#","With","the","default","shading","parameters",".",">",">",">","shading_filter","=","ShadingFilter","(",")",">",">",">","mesh","=","MeshVisual","(","vertices",",","faces",")",">",">",">","mesh.attach","(","shading_filter",")","The","filter","can","be","configured","at","creation","time","and","at","run","time",":",">",">",">","#","Configure","at","creation","time",".",">",">",">","shading_filter","=","ShadingFilter","(","...","#","A","shiny","surface","(","small","specular","highlight",")",".","...","shininess=250",",","...","#","A","blue","higlight",",","at","half","intensity",".","...","specular_coefficient=","(","0",",","0",",","1",",","0.5",")",",","...","#","Equivalent","to","`","(","0.7",",","0.7",",","0.7",",","1.0",")","`",".","...","diffuse_coefficient=0.7",",","...","#","Same","as","`","(","0.2",",","0.3",",","0.3",",","1.0",")","`",".","...","ambient_coefficient=","(","0.2",",","0.3",",","0.3",")",",","...",")",">",">",">","#","Change","the","configuration","at","run","time",".",">",">",">","shading_filter.shininess","=","64",">",">",">","shading_filter.specular_coefficient","=","0.3","Disable","the","filter","temporarily",":",">",">",">","#","Turn","off","the","shading",".",">",">",">","shading_filter.enabled","=","False","...","#","Some","time","passes","...",">",">",">","#","Turn","on","the","shading","again",".",">",">",">","shading_filter.enabled","=","True","When","using","the",":","class",":","`","WireframeFilter","`",",","the","wireframe","is","shaded","only","if","the","wireframe","filter","is","attached","before","the","shading","filter",":",">",">",">","shading_filter","=","ShadingFilter","(",")",">",">",">","wireframe_filter","=","WireframeFilter","(",")",">",">",">","#","Option","1",":","Shade","the","wireframe",".",">",">",">","mesh1","=","MeshVisual","(","vertices",",","faces",")",">",">",">","mesh1.attached","(","wireframe_filter",")",">",">",">","mesh1.attached","(","shading_filter",")",">",">",">","#","Option","2",":","Do","not","shade","the","wireframe",".",">",">",">","mesh2","=","MeshVisual","(","vertices",",","faces",")",">",">",">","mesh2.attached","(","shading_filter",")",">",">",">","mesh2.attached","(","wireframe_filter",")","See","also","`","examples\/basics\/scene\/mesh_shading.py","<","https",":","\/\/github.com\/vispy\/vispy\/blob\/main\/examples\/basics\/scene\/mesh_shading.py",">","`","_","example","script","."]
docstr: The specular reflection coefficient.
docstr_tok: ["The","specular","reflection","coefficient","."]
code: def specular_coefficient(self):
      """The specular reflection coefficient."""
      return self._specular_coefficient
  
imports: import numbers
  import numpy
  from vispy.gloo import Texture2D, VertexBuffer
  from vispy.visuals.shaders import Function, Varying
  from vispy.visuals.filters import Filter, PrimitivePickingFilter
  from ...color import Color
label_desc: Use image node_id 18 for calling the ShadingFilter obj's underlying member method code with example usage: obj.specular_coefficient() and returns: self