Graphics module is now complete. Added rdoc documentation to every class and method.

git-svn-id: https://sfml.svn.sourceforge.net/svnroot/sfml/branches/sfml2@1700 4e206d99-4929-0410-ac5d-dfc041789085

bindings/ruby/sfml-graphics/graphics/RenderTarget.cpp

@@ -37,6 +37,13 @@ extern VALUE globalDrawableModule;
 extern VALUE globalShaderClass;
 extern VALUE globalViewClass;
 
+/* call-seq:
+ *   render_target.clear( color = SFML::Color::Black )
+ *
+ * Clear the entire target with a single color.
+ *
+ * This function is usually called once every frame, to clear the previous contents of the target.
+ */
 static VALUE RenderTarget_Clear( int argc, VALUE *args, VALUE self )
 {
 	sf::Color color = sf::Color::Black;
@@ -62,6 +69,16 @@ static VALUE RenderTarget_Clear( int argc, VALUE *args, VALUE self )
 	return Qnil;
 }
 
+/* call-seq:
+ *   render_target.draw( drawable )
+ *   render_target.draw( drawable, shader )
+ *
+ * Draw an object into the target with a shader.
+ *
+ * This function draws anything that inherits from the SFML::Drawable base class (SFML::Sprite, SFML::Shape, SFML::Text, 
+ * or even your own derived classes). The shader alters the way that the pixels are processed right before being written 
+ * to the render target.
+ */
 static VALUE RenderTarget_Draw( int argc, VALUE *args, VALUE self )
 {
 	sf::RenderTarget *object = NULL;
@@ -94,6 +111,11 @@ static VALUE RenderTarget_Draw( int argc, VALUE *args, VALUE self )
 	return Qnil;
 }
 
+/* call-seq:
+ *   render_target.getWidth()	-> fixnum
+ *
+ * Return the width of the rendering region of the target. 
+ */
 static VALUE RenderTarget_GetWidth( VALUE self )
 {
 	sf::RenderTarget *object = NULL;
@@ -101,6 +123,11 @@ static VALUE RenderTarget_GetWidth( VALUE self )
 	return INT2FIX( object->GetWidth() );
 }
 
+/* call-seq:
+ *   render_target.getHeight()	-> fixnum
+ *
+ * Return the height of the rendering region of the target. 
+ */
 static VALUE RenderTarget_GetHeight( VALUE self )
 {
 	sf::RenderTarget *object = NULL;
@@ -108,6 +135,15 @@ static VALUE RenderTarget_GetHeight( VALUE self )
 	return INT2FIX( object->GetHeight() );
 }
 
+/* call-seq:
+ *   render_target.setView( view )
+ *
+ * Change the current active view.
+ *
+ * The new view will affect everything that is drawn, until another view is activated. The render target keeps its own
+ * copy of the view object, so it is not necessary to keep the original one alive as long as it is in use. To restore
+ * the original view of the target, you can pass the result of getDefaultView() to this function.
+ */
 static VALUE RenderTarget_SetView( VALUE self, VALUE aView )
 {
 	VALIDATE_CLASS( aView, globalViewClass, "view" );
@@ -119,6 +155,11 @@ static VALUE RenderTarget_SetView( VALUE self, VALUE aView )
 	return Qnil;
 }
 
+/* call-seq:
+ *   render_target.getView()	-> view
+ *
+ * Retrieve the view currently in use in the render target. 
+ */
 static VALUE RenderTarget_GetView( VALUE self )
 {
 	sf::RenderTarget *object = NULL;
@@ -129,6 +170,13 @@ static VALUE RenderTarget_GetView( VALUE self )
 	return rbData;
 }
 
+/* call-seq:
+ *   render_target.getDefaultView()	-> VIEW
+ *
+ * Get the default view of the render target.
+ *
+ * The default view has the initial size of the render target, and never changes after the target has been created.
+ */
 static VALUE RenderTarget_GetDefaultView( VALUE self )
 {
 	sf::RenderTarget *object = NULL;
@@ -139,6 +187,14 @@ static VALUE RenderTarget_GetDefaultView( VALUE self )
 	return rbData;
 }
 
+/* call-seq:
+ *   render_target.getViewport( view )	-> rectangle
+ *
+ * Get the viewport of a view, applied to this render target.
+ *
+ * The viewport is defined in the view as a ratio, this function simply applies this ratio to the current dimensions 
+ * of the render target to calculate the pixels rectangle that the viewport actually covers in the target.
+ */
 static VALUE RenderTarget_GetViewport( VALUE self, VALUE aView )
 {
 	VALIDATE_CLASS( aView, globalViewClass, "view" );
@@ -152,6 +208,19 @@ static VALUE RenderTarget_GetViewport( VALUE self, VALUE aView )
 				INT2FIX( viewport.Width ), INT2FIX( viewport.Height ) );
 }
 
+/* call-seq:
+ *   render_target.convertCoords( x, y )	-> vector2
+ *   render_target.convertCoords( x, y, view )	-> vector2
+ *
+ * Convert a point from target coordinates to view coordinates.
+ *
+ * Initially, a unit of the 2D world matches a pixel of the render target. But if you define a custom view, this 
+ * assertion is not true anymore, ie. a point located at (10, 50) in your render target (for example a window) may 
+ * map to the point (150, 75) in your 2D world -- for example if the view is translated by (140, 25).
+ *
+ * For render windows, this function is typically used to find which point (or object) is located below the mouse cursor.
+ *
+ */
 static VALUE RenderTarget_ConvertCoords( int argc, VALUE *args, VALUE self )
 {
 	sf::RenderTarget *object = NULL;
@@ -177,6 +246,30 @@ static VALUE RenderTarget_ConvertCoords( int argc, VALUE *args, VALUE self )
 	return rb_funcall( globalVector2Class, rb_intern( "new" ), 2, rb_float_new( result.x ), rb_float_new( result.y ) );
 }
 
+/* call-seq:
+ *   render_target.saveGLStates()
+ *
+ * Save the current OpenGL render states and matrices.
+ *
+ * This function can be used when you mix SFML drawing and direct OpenGL rendering. Combined with RestoreGLStates, 
+ * it ensures that:
+ *
+ *   - SFML's internal states are not messed up by your OpenGL code
+ *   - your OpenGL states are not modified by a call to a SFML function
+ *
+ * More specifically, it must be used around code that calls Draw functions. Example:
+ *
+ *   # OpenGL code here...
+ *   window.saveGLStates()
+ *   window.draw(...)
+ *   window.draw(...)
+ *   window.restoreGLStates()
+ *   # OpenGL code here...
+ *
+ * Note that this function is quite expensive and should be used wisely. It is provided for convenience, and the 
+ * best results will be achieved if you handle OpenGL states yourself (because you really know which states have 
+ * really changed, and need to be saved / restored).
+ */
 static VALUE RenderTarget_SaveGLStates( VALUE self )
 {
 	sf::RenderTarget *object = NULL;
@@ -185,6 +278,13 @@ static VALUE RenderTarget_SaveGLStates( VALUE self )
 	return Qnil;
 }
 
+/* call-seq:
+ *   render_target.restoreGLStates()
+ *
+ * Restore the previously saved OpenGL render states and matrices.
+ *
+ * See the description of saveGLStates to get a detailed description of these functions.
+ */
 static VALUE RenderTarget_RestoreGLStates( VALUE self )
 {
 	sf::RenderTarget *object = NULL;