commenting

private/blah/internal/graphics_backend.h

@@ -3,22 +3,51 @@
 
 namespace Blah
 {
+	// Graphics backend API used for rendering.
+	// All rendering ends up going through here.
 	namespace GraphicsBackend
 	{
+		// Initializes the graphics backend
 		bool init();
+
+		// Shuts down the graphics backend
 		void shutdown();
 
+		// Returns info about the renderer
 		const GraphicsInfo* info();
+
+		// Returns the renderer type
 		GraphicsRenderer renderer();
+
+		// Called once per frame
 		void frame();
+
+		// Called before rendering begins
 		void before_render();
+
+		// Called after renderings ends
 		void after_render();
+
+		// Performs a draw call
 		void render(RenderCall* call);
+
+		// Clears a buffer
 		void clear(const FrameBufferRef& target, uint32_t rgba);
 
+		// Creates a new Texture.
+		// if the Texture is invalid, this should return an empty reference.
 		TextureRef create_texture(int width, int height, TextureFilter filter, TextureWrap wrap_x, TextureWrap wrap_y, TextureFormat format);
+
+		// Creates a new FrameBuffer.
+		// if the FrameBuffer is invalid, this should return an empty reference.
 		FrameBufferRef create_framebuffer(int width, int height, const TextureFormat* attachments, int attachmentCount);
+
+		// Creates a new Shader.
+		// if the Shader is invalid, this should return an empty reference.
 		ShaderRef create_shader(const ShaderData* data);
+
+		// Creates a new Mesh.
+		// if the Mesh is invalid, this should return an empty reference.
 		MeshRef create_mesh();
 	}
 }

public/blah/drawing/batch.h

@@ -12,7 +12,6 @@
 
 namespace Blah
 {
-
 	enum class ColorMode
 	{
 		Normal,
@@ -39,30 +38,72 @@ namespace Blah
 	class Batch
 	{
 	public:
+
+		// The name of the Matrix Uniform in the Shader
+		const char* matrix_uniform;
+
+		// The name of the Texture Uniform in the Shader
+		const char* texture_uniform;
+
 		Batch();
 		Batch(const Batch& other) = delete;
 		Batch& operator=(const Batch& other) = delete;
 		~Batch();
 
+		// Pushes a new matrix onto the stack, and uses it for transforming all drawing.
+		// `absolute` means the matrix provided will not be transformed by the current stack.
 		void push_matrix(const Mat3x2& matrix, bool absolute = false);
+
+		// Pops the matrix from the stack
 		Mat3x2 pop_matrix();
+
+		// Pushes a Scissor rectangle. Note this is not transformed by the matrix stack
+		// or other scissors. Each push is screen-space.
 		void push_scissor(const Rect& scissor);
+
+		// Pops a Scissor rectangle from the stack
 		void pop_scissor();
+
+		// Pushes a blend mode
 		void push_blend(const BlendMode& blend);
+
+		// Pops a blend mode
 		void pop_blend();
+
+		// Pushes a Material to use for all drawing. Note that the state of the Material
+		// is not copied - it will be drawn with the values of the Material at render.
 		void push_material(const MaterialRef& material);
+
+		// Pops a Material
 		void pop_material();
+
+		// Pushes a render layer. Lower values are rendered first. This is not super optimized
+		// and should generally be avoided.
 		void push_layer(int layer);
+
+		// Pops a Layer
 		void pop_layer();
+
+		// Pushes a Color Mode for drawing Textures
 		void push_color_mode(ColorMode mode);
+
+		// Pops a Color MOde
 		void pop_color_mode();
 
+		// Sets the current texture used for drawing. Note that certain functions will override
+		// this (ex the `str` and `tex` methods)
 		void set_texture(const TextureRef& texture);
 
+		// Draws the batch to the given target
 		void render(const FrameBufferRef& target);
+
+		// Draws the batch to the given target, with the provided matrix
 		void render(const FrameBufferRef& target, const Mat4x4& matrix);
 
+		// Clears the batch
 		void clear();
+
+		// Clears and disposes all resources that the batch is using
 		void dispose();
 
 		void line(const Vec2& from, const Vec2& to, float t, Color color);
@@ -105,12 +146,10 @@ namespace Blah
 		void tex();
 		void tex(const Subtexture& subtexture, const Vec2& pos, Color color);
 		void tex(const Subtexture& subtexture, const Vec2& pos, const Vec2& origin, const Vec2& scale, float rotation, Color color);
+
 		void str(const SpriteFont& font, const String& text, const Vec2& pos, Color color);
 		void str(const SpriteFont& font, const String& text, const Vec2& pos, TextAlign align, float size, Color color);
 
-		const char* matrix_uniform;
-		const char* texture_uniform;
-
 	private:
 
 		struct Vertex

public/blah/drawing/subtexture.cpp

@@ -2,10 +2,13 @@
 
 using namespace Blah;
 
-Subtexture::Subtexture()
-{
+Subtexture::Subtexture() {}
 
-}
+Subtexture::Subtexture(const TextureRef& texture)
+	: Subtexture(texture, Rect(0, 0, texture->width(), texture->height())) {}
+
+Subtexture::Subtexture(const TextureRef& texture, Rect source)
+	: Subtexture(texture, source, Rect(0, 0, source.w, source.h)) {}
 
 Subtexture::Subtexture(const TextureRef& texture, Rect source, Rect frame)
 	: texture(texture), source(source), frame(frame)

public/blah/drawing/subtexture.h

@@ -6,19 +6,35 @@ namespace Blah
 {
 	struct Subtexture
 	{
-		TextureRef	texture;
-		Rect		source;
-		Rect		frame;
-		Vec2		draw_coords[4];	// draw coords are automatically assigned through Update method
-		Vec2		tex_coords[4];	// tex coords are automatically assigned through Update method
+		// Reference to our Texture
+		TextureRef texture;
+
+		// Source rectangle, in pixels
+		Rect source;
+
+		// Frame rectangle, in pixels. This describes padding around the image.
+		// This is useful for drawing images that have been trimmed. Ex. if the source
+		// is 32,32, but the original image was 64,64, the frame could be -16,-16,64,64
+		Rect frame;
+
+		// `draw_coords` are automatically assigned through `update` method
+		Vec2 draw_coords[4];
+
+		// `tex_coords` are automatically assigned through the `update` method
+		Vec2 tex_coords[4];
 
 		Subtexture();
+		Subtexture(const TextureRef& texture);
+		Subtexture(const TextureRef& texture, Rect source);
 		Subtexture(const TextureRef& texture, Rect source, Rect frame);
 
+		// Returns the width of the image
 		float width() const { return frame.w; }
+
+		// Returns the height of the image
 		float height() const { return frame.h; }
 
-		// updates the draw and tex coords
+		// updates the `draw_coords` and `tex_coords`
 		void update();
 	};
 }