Inherits from NSObject
Conforms to NGLShaders
Declared in NGLShaders.h

Overview

The custom shaders.

NinevehGL works internally with its own shaders based on NGLMaterial. However, you can create your very own shaders, loading them from files or writing the source code.

There are three important optionals properties you can set: the vertex shader, the fragment shader and the variables to the pair of shaders. The NinevehGL’s core will join those optionals properties with its own shaders, creating a new unique shader behavior to your mesh.

Never call the variables property directly, it’s reserved only for you to check the current variables. Use one of the bind* methods to set a shader variable and removeVariableWithName: to remove a shader variable.

When you call one of the bind* methods you specify a pointer to data, by doing so any new changes to the pointed data will imediatly change the shader variable value.

NGLShaders is identified by its identifier property (ID). If its ID doesn’t match with one of the NGLSurface’s ID, it will be ignored on the mesh’s compilation phase. If there is no NGLSurface specified, the first NGLShader will be used.

All the shader variables are optimized to mediump or lowp whenever is possible, according to their purposes.

The NinevehGL’s vertex variables are:

  • attribute vec4 a_nglPosition: The vertex position, per-vertex.
  • attribute vec2 a_nglTexcoord: [optional] Used only when exist Texture Coordinates. Stores the Texture Coordinate Vectors, per-vertex.
  • attribute vec3 a_nglNormal: [optional] Used only when exist Normals. Stores the Normal Vectors, per-vertex.
  • attribute vec3 a_nglTangent: [optional] Used only when exist Light Effect + Tangent Space. Stores the Tangent Vectors, per-vertex.
  • attribute vec3 a_nglBitangent: [optional] Used only when exist Light Effect + Tangent Space. Stores the Bitangent Vector, per-vertex.

The NinevehGL’s fragment variables are:

  • vec4 _nglEmission: Represents the emissive color component.
  • vec4 _nglAmbient: Represents the ambient color component.
  • vec4 _nglDiffuse: Represents the diffuse color component.
  • vec4 _nglSpecular: Represents the specular color component.
  • vec4 _nglLightness: Represents the lightness color component.
  • float _nglShininess: Represents the shininess color component.
  • float _nglAlpha: Represents the alpha component.
  • varying vec2 v_nglTexcoord: [optional] Only if exist Texture Coordinates. Represents the texture coordinates.
  • varying vec3 v_nglNormal: [optional] Used only when exist Normals. Represents the normals.
  • vec3 v_nglVEye: [optional] Used only when exist Light Effect. It’s the calculated “Eye Vector”, which is used in many light computations.
  • vec3 v_nglVLight: [optional] Used only when exist Light Effect. It’s the calculated “Light Vector”, which is used in many light computations.
  • vec3 _nglNormal: [optional] The normalized v_nglNormal.
  • vec3 _nglVEye: [optional] The normalized v_nglEye.
  • vec3 _nglVLight: [optional] The normalized v_nglLight.
  • float v_nglLightLevel: [optional] Only when exist Light Effect. It’s the calculated light intensity, which is used in many light computations.
  • float _nglLightD: [optional] Used only when exist Light Effect. It’s the Light Delta, the calculated dot product between the “Normal Vector” and the “Light Vector” (NdotL), which is used in many light computations.
  • float _nglShineD: [optional] Used only when exist Light Effect. It’s the Shine Delta, the calculated dot product between the “Normal Vector” and “Half Vector” or the “Reflected” (NdotH or NdotR). The NdotR will be used in displacement calculations, like bump maps, otherwise, the NdotH will be used in place to boost the performance.
  • float v_nglFog: [optional] Used only when exist Fog effect. Represents the final fog percentage in the range (0.0, 1.0).

The NinevehGL’s Uniforms can be used in any shader, although they will be used by NinevehGL in the indicated shader, in this case you don’t need to redefine them in the shader’s header:

  • uniform mat4 u_nglMVPMatrix: (vertex) The Model View Projection Matrix for a mesh.
  • uniform mat4 u_nglMIMatrix: (vertex) [optional] Used only when exist Light Effect. Represents the inverse Model Matrix.
  • uniform mat4 u_nglWIMatrix: (vertex) [optional] Used only when exist Light Effect. Represents the inverse World Matrix (Model + View).
  • uniform vec4 u_nglLightPosition: (vertex) [optional] Used only when exist Light Effect. Represents the light position.
  • uniform float u_nglLightAttenuation: (vertex) [optional] Used only when exist Light Effect. Represents the light attenuation factor.
  • uniform vec4 u_nglLightColor: (fragment) [optional] Used only when exist Light Effect. Represents the light color.
  • uniform float u_nglAlpha: (fragment) Represents the alpha component color.
  • uniform sampler2D u_nglAlphaMap: (fragment) [optional] Only if exist Texture Coordinates + Alpha Map. Replaces the ambient color component.
  • uniform vec4 u_nglAmbientColor: (fragment) Represents the ambient color component.
  • uniform sampler2D u_nglAmbientMap: (fragment) [optional] Only if exist Texture Coordinates + Ambient Map. Replaces the ambient color component.
  • uniform vec4 u_nglDiffuseColor: (fragment) Represents the diffuse color component.
  • uniform sampler2D u_nglDiffuseMap: (fragment) [optional] Only if exist Texture Coordinates + Diffuse Map. Replaces the diffuse color component.
  • uniform vec4 u_nglEmissiveColor: (fragment) Represents the emissive color component.
  • uniform sampler2D u_nglEmissiveMap: (fragment) [optional] Only if exist Texture Coordinates + Emissive Map. Replaces the emissive color component.
  • uniform vec4 u_nglSpecularColor: (fragment) Represents the specular color component.
  • uniform sampler2D u_nglSpecularMap: (fragment) [optional] Only if exist Texture Coordinates + Specular Map. Replaces the specular color component.
  • uniform float u_nglShininess: (fragment) Represents the shininess light component.
  • uniform sampler2D u_nglShininessMap: (fragment) [optional] Only if exist Texture Coordinates + Shininess Map. Replaces the shininess component.
  • uniform sampler2D u_nglBumpMap: (fragment) [optional] Only if exist Texture Coordinates + Bump Map. Represents the bump texture map.
  • uniform sampler2D u_nglReflMap: (fragment) [optional] Only if exist Normals + Reflective Map. Represents the reflection map.
  • uniform float u_nglReflLevel: (fragment) [optional] Only if exist Normals + Reflective Map. Represents the reflection level.
  • uniform vec4 u_nglFogColor: (fragment) [optional] Used only when exist Fog effect. Represents the fog color.
  • uniform float u_nglFogEnd: (vertex) [optional] Used only when exist Fog effect. Represents the end distance.
  • uniform float u_nglFogFactor: (vertex) [optional] Used only when exist Fog effect. Represents the precalculated fog factor.

Tasks

Properties

fragment

Represents the custom fragment shader.

@property (nonatomic, readonly) NGLSLShader *fragment

Discussion

Represents the custom fragment shader.

Declared In

NGLShaders.h

identifier

The identifier of this object.

@property (nonatomic) unsigned int identifier

Discussion

The identifier of this object.

Declared In

NGLShaders.h

variables

Represents the custom shader variables. Never call this property directly to set or remove a variable from these shaders. Instead, make use one of the bind* methods to add a variable and removeVariableWithName: to remove one of them.

@property (nonatomic, readonly) NGLSLVariables *variables

Discussion

Represents the custom shader variables. Never call this property directly to set or remove a variable from these shaders. Instead, make use one of the bind* methods to add a variable and removeVariableWithName: to remove one of them.

Declared In

NGLShaders.h

vertex

Represents the custom vertex shader.

@property (nonatomic, readonly) NGLSLShader *vertex

Discussion

Represents the custom vertex shader.

Declared In

NGLShaders.h

Class Methods

shadersWithFileVertex:andFragment:

Returns an autorelease instance of NGLShaders.

+ (id)shadersWithFileVertex:(NSString *)vshPath andFragment:(NSString *)fshPath

Parameters

vshPath

A NSString representing the file path for the vertex shader.

fshPath

A NSString representing the file path for the fragment shader.

Return Value

A new initialized NGLShaders instance.

Discussion

Returns an autorelease instance of NGLShaders.

This method creates a shader pair with the source code from file(s).

Declared In

NGLShaders.h

shadersWithSourceVertex:andFragment:

Returns an autorelease instance of NGLShaders.

+ (id)shadersWithSourceVertex:(NSString *)vsh andFragment:(NSString *)fsh

Parameters

vsh

A NSString containing source code for the vertex shader.

fsh

A NSString containing source code for the fragment shader.

Return Value

A NGLShaders autoreleased instance.

Discussion

Returns an autorelease instance of NGLShaders.

This method creates a shader pair with some source code in it.

Declared In

NGLShaders.h

Instance Methods

bindAttribute:stride:dataType:data:

Creates and binds a new attribute variable to the shaders.

- (void)bindAttribute:(NSString *)name stride:(int)stride dataType:(int)dataType data:(void *)data

Parameters

name

A NSString containing exactly the same name as the variable has inside the shaders.

stride

The stride of each set of values. This value is given in basic machine units (bytes).

dataType

The shader data type. You must use one of the NinevehGL correlated definitions:

  • NGL_FLOAT = float;
  • NGL_VEC2 = vec2;
  • NGL_VEC3 = vec3;
  • NGL_VEC4 = vec4;
  • NGL_MAT2 = mat2;
  • NGL_MAT3 = mat3;
  • NGL_MAT4 = mat4.

Attributes just accept floating points data types.

data

A pointer to the data source.

Discussion

Creates and binds a new attribute variable to the shaders.

The attribute represents a dynamic value. Usually its data are an array where each element represents a value to be used during a vertex processing. Values that are intended to be constant through all the vertices, should be Uniforms rather than Attributes.

Declared In

NGLShaders.h

bindTexture:texture:

Creates and binds a new texture variable to the shaders.

- (void)bindTexture:(NSString *)name texture:(NGLTexture *)texture

Parameters

name

A NSString containing exactly the same name as the variable has inside the shaders.

texture

The initialized NGLTexture instance.

Discussion

Creates and binds a new texture variable to the shaders.

This method is specific for any kind of textures in the shaders, as the textures form a special data type group in GLSL. It’ll bind a NGLTexture with a shader variable uniform. The data type will depend on the NGLTexture type.

Declared In

NGLShaders.h

bindUniform:count:dataType:data:

Creates and binds a new uniform variable to the shaders.

- (void)bindUniform:(NSString *)name count:(int)count dataType:(int)dataType data:(void *)data

Parameters

name

A NSString containing exactly the same name as the variable has inside the shaders.

count

The elements count. For array it should be the array’s length, for single instances it should be 1.

dataType

The shader data type. You must use one of the NinevehGL correlated definitions:

  • NGL_FLOAT = float;
  • NGL_INT = int;
  • NGL_BOOL = bool;
  • NGL_VEC2 = vec2;
  • NGL_VEC3 = vec3;
  • NGL_VEC4 = vec4;
  • NGL_IVEC2 = ivec2;
  • NGL_IVEC3 = ivec3;
  • NGL_IVEC4 = ivec4;
  • NGL_BVEC2 = bvec2;
  • NGL_BVEC3 = bvec3;
  • NGL_BVEC4 = bvec4;
  • NGL_MAT2 = mat2;
  • NGL_MAT3 = mat3;
  • NGL_MAT4 = mat4;
data

A pointer to the data source.

Discussion

Creates and binds a new uniform variable to the shaders.

The uniform represents a constant value. Its data can be a single instance or an array. In case of an arrays of uniforms, you must specify the array’s length with the #count# param.

Declared In

NGLShaders.h

initWithFileVertex:andFragment:

Initializes this NGLShaders with one or two shader inside.

- (id)initWithFileVertex:(NSString *)vshPath andFragment:(NSString *)fshPath

Parameters

vshPath

A NSString representing the file path for the vertex shader.

fshPath

A NSString representing the file path for the fragment shader.

Return Value

A new initialized NGLShaders instance.

Discussion

Initializes this NGLShaders with one or two shader inside.

Declared In

NGLShaders.h

initWithSourceVertex:andFragment:

Initializes this NGLShaders with one or two shaders inside.

- (id)initWithSourceVertex:(NSString *)vsh andFragment:(NSString *)fsh

Parameters

vsh

A NSString containing source code for the vertex shader.

fsh

A NSString containing source code for the fragment shader.

Return Value

A new initialized NGLShaders instance.

Discussion

Initializes this NGLShaders with one or two shaders inside.

Declared In

NGLShaders.h

removeVariableWithName:

Removes a variable previously bound to the shaders.

- (void)removeVariableWithName:(NSString *)name

Parameters

name

A NSString containing exactly the same name as the variable has inside the shaders.

Discussion

Removes a variable previously bound to the shaders.

This method will remove a specific variable which was previously bound to these shaders.

Declared In

NGLShaders.h