Some comments.

--HG--
branch : gsoc2013-dfighter

code/nel/include/nel/3d/driver.h

@@ -1036,16 +1036,34 @@ public:
 	/// Creates a new Pixel program
 	virtual IProgram*		createPixelProgram() const { return NULL; }
 
+	/// Returns the location of the specified uniform, or -1 if it's not found
 	virtual int getUniformLocation( const char *name ){ return -1; }
 
+	/// Sets a single float uniform
 	virtual void setUniform1f( uint index, float f ){}
+
+	/// Sets 4 floats uniform value ( vector )
 	virtual void setUniform4f( uint index, float f1, float f2, float f3, float f4  ){}
+
+	/// Sets a single integer uniform value
 	virtual void setUniform1i( uint index, int i ){}
+
+	/// Sets a 4 integer uniform value ( vector )
 	virtual void setUniform4i( uint index, int i1, int i2, int i3, int i4 ){}
+
+	/// Sets a single unsigned integer uniform value
 	virtual void setUniform1u( uint index, uint u ){}
+
+	/// Sets a 4 unsigned integer uniform value
 	virtual void setUniform4u( uint index, uint u1, uint u2, uint u3, uint u4 ){}
+
+	/// Sets a 2x2 float matrix uniform value ( column major order )
 	virtual void setUniformMatrix2fv( uint index, uint count, bool transpose, const float *values ){}
+
+	/// Sets a 3x3 float matrix uniform value ( column major order )
 	virtual void setUniformMatrix3fv( uint index, uint count, bool transpose, const float *values ){}
+
+	/// Sets a 4x4 float matrix uniform value ( column major order )
 	virtual void setUniformMatrix4fv( uint index, uint count, bool transpose, const float *values ){}
 
 	/**
@@ -1301,6 +1319,7 @@ private:
 	bool			_StaticMemoryToVRAM;
 
 public:
+	/// Reloads the user shaders
 	virtual void reloadUserShaders(){}
 };
 

code/nel/include/nel/3d/dynamic_material.h

@@ -25,7 +25,7 @@
 
 namespace NL3D
 {
-
+	/// Rendering property
 	struct SDynMaterialProp
 	{
 		enum EPropertyType
@@ -40,8 +40,13 @@ namespace NL3D
 			Texture
 		};
 
+		/// Id of the property
 		std::string prop;
+
+		/// Label of the property ( user-friendly name )
 		std::string label;
+
+		/// type of the property ( see EPropertyType )
 		uint8 type;
 
 		NLMISC::CVariant value;
@@ -50,7 +55,7 @@ namespace NL3D
 	};
 
 
-
+	/// Rendering pass data, contains the rendering properties for the pass
 	struct SRenderPass
 	{
 	public:
@@ -63,8 +68,12 @@ namespace NL3D
 		void setShaderRef( const std::string &s ){ shaderRef = s; }
 		void serial( NLMISC::IStream &f );
 
+		/// Returns the number of properties this pass has
 		uint32 count(){ return properties.size(); }
+
+		/// Clears all properties
 		void clear(){ properties.clear(); }
+
 		const SDynMaterialProp* getProperty( uint32 i ) const;
 
 	private:
@@ -75,7 +84,7 @@ namespace NL3D
 
 
 
-
+	/// Multi-pass material for rendering using user shaders
 	class CDynMaterial : public NLMISC::IStreamable
 	{
 	public:
@@ -83,7 +92,10 @@ namespace NL3D
 		~CDynMaterial();
 		CDynMaterial& operator=( const CDynMaterial &other );
 
+		/// Clears all passes, and then adds a new pass
 		void reconstruct();
+
+		/// Clears all passes
 		void clear();
 		void serial( NLMISC::IStream &f );
 		std::string getClassName(){ return "CDynMaterial"; }

code/nel/include/nel/3d/usr_shader_manager.h

@@ -27,17 +27,32 @@ namespace NL3D
 	class CUsrShaderProgram;
 	class IUsrShaderVisitor;
 
+	/// Manages user defined shaders ( add, remove, change )
 	class CUsrShaderManager
 	{
 	public:
 		CUsrShaderManager();
 		~CUsrShaderManager();
+
+		/// Throw away the currently loaded shaders
 		void clear();
+
+		/// Returns a list of the currently loaded shaders
 		void getShaderList( std::vector< std::string > &v );
+
+		/// Adds a shader
 		bool addShader( CUsrShaderProgram *program );
+
+		/// Removes a shader
 		bool removeShader( const std::string &name );
+
+		/// Changes a shader
 		bool changeShader( const std::string &name, CUsrShaderProgram *program );
+
+		/// Looks up and returns a shader
 		bool getShader( const std::string &name, CUsrShaderProgram *program );
+
+
 		void visitShaders( IUsrShaderVisitor *visitor );
 		void visitShader( const std::string &name, IUsrShaderVisitor *visitor );
 

code/nel/src/3d/driver/OpenGL3/driver_glsl_shader_generator.cpp

@@ -136,6 +136,7 @@ namespace NL3D
 	{
 		material = NULL;
 		vbFormat = 0;
+		desc = NULL;
 		ss.str( "" );
 		ss.clear();
 	}

code/nel/src/3d/driver/OpenGL3/driver_glsl_shader_generator.h

@@ -26,14 +26,20 @@ namespace NL3D
 	class CMaterial;
 	class CShaderDesc;
 
+	/// GLSL 330+ shader program generator
 	class CGLSLShaderGenerator
 	{
 	public:
 		CGLSLShaderGenerator();
 		~CGLSLShaderGenerator();
+
+		/// Resets the generator to 0.
 		void reset();
 
+		/// Generate Vertex Shader based on the data provided in material, descriptor and vertexbuffer flags
 		void generateVS( std::string &vs );
+
+		/// Generate Pixel Shader based on the data provided in material, descriptor and vertexbuffer flags
 		void generatePS( std::string &ps );
 
 		void setMaterial( CMaterial *mat ){ material = mat; }
@@ -41,32 +47,83 @@ namespace NL3D
 		void setShaderDesc( CShaderDesc *d ){ desc = d; }
 
 	private:
+		/// Adds diffuse constant uniform declaration  to the program
 		void addDiffuse();
+
+		/// Adds Color constant uniform declaration to the program
 		void addColor();
+
+		/// Adds constant uniform declarations to the program
 		void addConstants();
+
+		/// Adds the normal matrix declaration to the program
 		void addNormalMatrix();
+
+		/// Adds the normal matrix calculating function to the program ( calculated from the inverse transpose of the upper left 3x3 part )
 		void addNormalFromMVFunction();
 		
+		//////////////////////////// Alpha Threshold //////////////////
+		
+		/// Adds the alpha threshold uniform to the program
 		void addAlphaTreshold();
+
+		/// Adds the actual alpha test to the program ( discards fragment if below threshold )
 		void addAlphaTest();
 
+		//////////////////////////////////////////////////////////////
+
+		/////////////////////////// Fog ///////////////////////////////
+		
+		/// Adds the fog uniforms to the program
 		void addFogUniform();
+
+		/// Adds the fog function to the program
 		void addFogFunction();
+
+		/// Adds the fog call to the program
 		void addFog();
 
+		///////////////////////////////////////////////////////////////
+
 		//////////////////////////// Lights ///////////////////////////
+		
+		/// Adds the Vertex Shader light uniforms to the program
 		void addLightUniformsVS();
+
+		/// Adds the Pixel Shader light uniforms to the program
 		void addLightUniformsFS();
+
+		/// Adds the Vertex Shader light output variables to the program
 		void addLightOutsVS();
+
+		/// Adds the Pixel Shader light output variables to the program
 		void addLightInsFS();
+
+		/// Adds the directional light Vertex Shader function, num is the light number
 		void addDirectionalFunctionVS( int num );
+
+		/// Adds the point-light Vertex Shader function, num is the light number
 		void addPointLightFunctionVS( int num );
+
+		/// Adds the appropriate light functions to the Vertex Shader
 		void addLightsFunctionVS();
+
+		/// Adds the appropriate light functions to the Pixel Shader
 		void addLightsFunctionFS();
+
+		/// Adds the lights to the Vertex Shader ( calls the appropriate functions )
 		void addLightsVS();
+
+		/// Adds the lights to the Fragment Shader ( calls the appropriate functions )
 		void addLightsFS();
+
 		//////////////////////////////////////////////////////////////
 
+
+
+		//////////////////////////////////////// Vertex Shader generation ////////////////////////////////////
+
+
 		void generateNormalVS();
 		void generateSpecularVS();
 
@@ -75,7 +132,15 @@ namespace NL3D
 
 		void generateWaterVS();
 
+
+		///////////////////////////////////////////////////////////////////////////////////////////////////////
+
+
+		/////////////////////////////////////// Pixel Shader generation ///////////////////////////////////////
+		
 		void generateNormalPS();
+		
+
 		void generateTexEnv();
 		void generateTexEnvRGB( unsigned int stage );
 		void generateTexEnvAlpha( unsigned int stage );
@@ -91,6 +156,8 @@ namespace NL3D
 
 		void generateCloudPS();
 
+		////////////////////////////////////////////////////////////////////////////////////////////////////////
+
 		std::stringstream ss;
 		uint16 vbFormat;
 		CMaterial const *material;

code/nel/src/3d/driver/OpenGL3/driver_opengl.h

@@ -1083,7 +1083,7 @@ private:
 	/// setup a texture stage with an UV from VB.
 	void			setupUVPtr(uint stage, CVertexBufferInfo &VB, uint uvId);
 
-
+	/// Sets up the rendering parameters for the normal shader
 	void setupNormalPass();
 
 
@@ -1376,7 +1376,10 @@ private:
 		CGLSLShaderGenerator *shaderGenerator;
 		CUsrShaderManager    *usrShaderManager;
 		
+		/// The program that is currently used
 		IProgramObject *currentProgram;
+
+		/// The current user shader program
 		IProgramObject *dynMatProgram;
 #endif
 

code/nel/src/3d/driver/OpenGL3/driver_opengl_shader_cache.h

@@ -23,14 +23,20 @@
 
 namespace NL3D
 {
+	/// Caches generated shaders, so they don't have to be generated every frame
 	class CShaderCache
 	{
 	public:
 		CShaderCache();
 		~CShaderCache();
 
+		/// Checks if there's a shader cached that was generated from the specified descriptor
 		IProgramObject* findShader( const CShaderDesc &desc ) const;
+
+		/// Caches a shader with the specified descriptor as key
 		void cacheShader( CShaderDesc &desc );
+
+		/// Clears the caches, removes the cached shaders
 		void clearCache();
 
 	private:

code/nel/tools/3d/object_viewer_qt/src/plugins/material_editor/nel3d_interface.h

@@ -33,7 +33,7 @@ namespace NL3D
 
 namespace MaterialEditor
 {
-
+	/// Material Property, holds the user shader parameters as string ( for the editor )
 	struct SMatProp
 	{
 		enum EType
@@ -49,7 +49,10 @@ namespace MaterialEditor
 			EType_count
 		};
 
+		/// Creates a string representation of the type id
 		static std::string typeIdToString( unsigned char type );
+
+		/// Turns the type id string back to Id
 		static unsigned char typeStringToId( const std::string &s );
 
 		std::string id;
@@ -61,6 +64,8 @@ namespace MaterialEditor
 		static const char *idToString[];
 	};
 
+
+	/// Proxy class for the rendering pass
 	class CRenderPassProxy
 	{
 	public:
@@ -71,21 +76,35 @@ namespace MaterialEditor
 
 		~CRenderPassProxy(){}
 
+		/// Retrieves the rendering properties as a vector
 		void getProperties( std::vector< SMatProp > &v );
+
+		/// Clears the properties and then copies the ones from the vector specified
 		void setProperties( std::vector< SMatProp > &v );
+
+		/// Retrieves the name of the pass
 		void getName( std::string &name );
+
+		/// Sets the name of the pass
 		void setName( const std::string &name );
+
+		/// Returns the reference ( just a string ) to the user shader associated
 		void getShaderRef( std::string &s );
+
+		/// Sets the reference ( just a string ) to the user shader associated
 		void setShaderRef( const std::string &s );
 
+		/// Retrieves a single rendering property
 		bool getProperty( const std::string &name, SMatProp &p );
+
+		/// Changes a single rendering property
 		bool changeProperty( const SMatProp &p );
 
 	private:
 		NL3D::SRenderPass *pass;
 	};
 
-
+	/// Proxy class for the dynamic material
 	class CNelMaterialProxy
 	{
 	public:
@@ -96,15 +115,28 @@ namespace MaterialEditor
 
 		~CNelMaterialProxy(){}
 
+		/// Retrieves the list of rendering passes
 		void getPassList( std::vector< std::string > &l );
 
+		/// Adds a new pass
 		void addPass( const char *name );
+
+		/// Removes the specified pass, if exists
 		void removePass( const char *name );
+
+		/// Moves the pass up by one position
 		void movePassUp( const char *name );
+
+		/// Moves the pass down by one position
 		void movePassDown( const char *name );
+
+		/// Renames the specified pass
 		void renamePass( const char *from, const char *to );
 
+		/// Retrieves the specified pass, by position
 		CRenderPassProxy getPass( unsigned long i );
+
+		/// Retrieves the specified pass, by name
 		CRenderPassProxy getPass( const char *name );
 
 		bool isEmpty() const{
@@ -134,38 +166,81 @@ namespace MaterialEditor
 		CNel3DInterface();
 		~CNel3DInterface();
 
+		/// Load a material for the current (sub)object
 		bool loadMaterial( const char *fname );
+
+		/// Save the current (sub)object's material
 		bool saveMaterial( const char *fname );
+
+		/// Generate materials from the current (sub)object(s) "old" material(s)
 		void genMaterials();
+
+		/// Creates new material(s) for the current (sub)object(s)
 		void newMaterial();
 
+		/// Makes the specified sub-material current
 		bool selectSubMaterial( int id );
-		CNelMaterialProxy getMaterial();
 
+		/// Returns a proxy object to the current sub-material
+		CNelMaterialProxy getMaterial();
 
+		/// Retrieves a list of user shaders loaded
 		void getShaderList( std::vector< std::string > &v );
+
+		/// Retrieves the specified user shader if exists
 		bool getShaderInfo( const std::string &name, SShaderInfo &info );
+
+		/// Updates a user shader
 		bool updateShaderInfo( const SShaderInfo &info );
+
+		/// Adds a new user shader
 		bool addShader( const SShaderInfo &info );
+
+		/// Removes a user shader
 		bool removeShader( const std::string &name );
 
+		/// Loads the user shaders
 		void loadShaders();
+
+		/// Saves the specified user shader
 		void saveShader( const std::string &name );
+
+		/// Deletes the specified user shader
 		void deleteShader( const std::string &name );
 
+		/// Sets up the viewport widget
 		void initViewPort( unsigned long wnd, unsigned long w, unsigned long h );
+
+		/// Shuts down the viewport widget
 		void killViewPort();
+
+		/// Resizes the viewport widget
 		void resizeViewPort( unsigned long w, unsigned long h );
 		NL3D::UDriver* getDriver(){ return driver; }
 
+		/// Clears the scene then adds a cube
 		bool addCube();
+
+		/// Clears the scene then adds a sphere
 		bool addSphere();
+
+		/// Clears the scene then add a cylinder
 		bool addCylinder();
+
+		/// Clears the scene the adds a teapot
 		bool addTeaPot();
 
+
+		/// Clears the scene then loads a shape
 		bool loadShape( const std::string &fileName );
+
+		/// Clears the scene, as the name suggests
 		void clearScene();
+
+		/// Sends the input events to Nel3D
 		void updateInput();
+
+		/// Renders the scene
 		void renderScene();
 
 		unsigned long getShapeMatCount() const;