Merging with latest.

Ultralight/platform/GPUDriver.h

@@ -30,11 +30,11 @@ namespace ultralight {
 /// RenderBuffer description, @see GPUDriver::CreateRenderBuffer.
 ///
 struct UExport RenderBuffer {
-  uint32_t texture_id;
-  uint32_t width;
-  uint32_t height;
-  bool has_stencil_buffer;
-  bool has_depth_buffer;
+  uint32_t texture_id;      // The backing texture for this RenderBuffer
+  uint32_t width;           // The width of the RenderBuffer texture
+  uint32_t height;          // The height of the RenderBuffer texture
+  bool has_stencil_buffer;  // Currently unused, always false.
+  bool has_depth_buffer;    // Currently unsued, always false.
 };
 
 ///
@@ -98,51 +98,85 @@ struct UExport IndexBuffer {
 ///
 /// Shader types, used by GPUState::shader_type
 ///
+/// Each of these correspond to a vertex/pixel shader pair. You can find
+/// stock shader code for these in the `shaders` folder of the AppCore repo.
+///
 enum UExport ShaderType {
-  kShaderType_Fill,
-  kShaderType_FillPath,
+  kShaderType_Fill,      // Shader program for quad geometry
+  kShaderType_FillPath,  // Shader program for path geometry
 };
 
 ///
 /// GPU state description.
 ///
 struct UExport GPUState {
+  /// Viewport width in logical units (multiply by device scale to get pixels).
   float viewport_width;
+
+  /// Viewport height in logical units (multiply by device scale to get pixels).
   float viewport_height;
+
+  /// Transform matrix-- you should multiply this with the screen-space
+  /// orthographic projection matrix then pass to the vertex shader.
   Matrix4x4 transform;
+
+  /// Whether or not we should enable texturing for the current draw command.
   bool enable_texturing;
+
+  /// Whether or not we should enable blending for the current draw command.
+  /// If blending is disabled, any drawn pixels should overwrite existing.
+  /// Mainly used so we can modify alpha values of the RenderBuffer during
+  /// scissored clears.
   bool enable_blend;
+
+  /// The vertex/pixel shader program pair to use for the current draw command.
+  /// You should cast this to ShaderType to get the corresponding enum.
   uint8_t shader_type;
+
+  /// The render buffer to use for the current draw command.
   uint32_t render_buffer_id;
+
+  /// The texture id to bind to slot #1. (Will be 0 if none)
   uint32_t texture_1_id;
+
+  /// The texture id to bind to slot #2. (Will be 0 if none)
   uint32_t texture_2_id;
+
+  /// The texture id to bind to slot #3. (Will be 0 if none)
   uint32_t texture_3_id;
+
+  /// The following four members are passed to the pixel shader via uniforms.
   float uniform_scalar[8];
   vec4 uniform_vector[8];
   uint8_t clip_size;
   Matrix4x4 clip[8];
+
+  /// Whether or not scissor testing should be used for the current draw command.
   bool enable_scissor;
+
+  /// The scissor rect to use for scissor testing (in logical units, you should
+  /// multiply by device scale to get pixel units).
   Rect scissor_rect;
 };
 
 ///
 /// Command types, used by Command::command_type
 ///
 enum UExport CommandType {
-  kCommandType_ClearRenderBuffer,
-  kCommandType_DrawGeometry,
+  kCommandType_ClearRenderBuffer,  // Corresponds to ClearRenderBuffer()
+  kCommandType_DrawGeometry,       // Corresponds to DrawGeometry()
 };
 
 ///
 /// Command description, handling one of these should result in either a call to
 /// GPUDriver::ClearRenderBuffer or GPUDriver::DrawGeometry.
 ///
 struct UExport Command {
-  uint8_t command_type;
-  GPUState gpu_state;
-  uint32_t geometry_id;
-  uint32_t indices_count;
-  uint32_t indices_offset;
+  uint8_t command_type;    // The type of command to dispatch.
+  GPUState gpu_state;      // GPU state parameters for current command.
+  uint32_t geometry_id;    // Used with DrawGeometry, the geometry ID to bind.
+  uint32_t indices_count;  // Used with DrawGeometry, the number of indices.
+  uint32_t indices_offset; // Used with DrawGeometry, the index to start from.
 };
 
 ///
@@ -184,8 +218,12 @@ class UExport GPUDriver {
   ///
   virtual uint32_t NextTextureId() = 0;
 
-  /// Create a texture with a certain ID and optional bitmap. If the Bitmap is
-  /// empty (Bitmap::IsEmpty), then a RTT Texture should be created instead.
+  ///
+  /// Create a texture with a certain ID and optional bitmap.
+  ///
+  /// **NOTE**: If the Bitmap is empty (Bitmap::IsEmpty), then a RTT Texture
+  ///           should be created instead. This will be used as a backing
+  ///           texture for a new RenderBuffer.
   ///
   virtual void CreateTexture(uint32_t texture_id,
                              Ref<Bitmap> bitmap) = 0;
@@ -199,6 +237,9 @@ class UExport GPUDriver {
   ///
   /// Bind a texture to a certain texture unit.
   ///
+  /// **NOTE**: This is not called directly by Ultralight-- you are expected to
+  ///           call this from your own implementation during drawing.
+  ///
   virtual void BindTexture(uint8_t texture_unit,
                            uint32_t texture_id) = 0;
 
@@ -219,13 +260,19 @@ class UExport GPUDriver {
                                   const RenderBuffer& buffer) = 0;
 
   ///
-  /// Bind a render buffer
+  /// Bind a render buffer.
+  ///
+  /// **NOTE**: This is not called directly by Ultralight-- you are expected to
+  ///           call this from your own implementation during drawing.
   ///
   virtual void BindRenderBuffer(uint32_t render_buffer_id) = 0;
 
   ///
   /// Clear a render buffer (flush pixels to 0).
   ///
+  /// **NOTE**: This is not called directly by Ultralight-- you are expected to
+  ///           call this from your own implementation during drawing.
+  ///
   virtual void ClearRenderBuffer(uint32_t render_buffer_id) = 0;
 
   ///
@@ -276,8 +323,11 @@ class UExport GPUDriver {
   virtual bool HasCommandsPending() = 0;
 
   ///
-  /// Iterate through stored command list and dispatch to ClearRenderBuffer or
-  /// DrawGeometry, respectively. Command list should be cleared at end of call.
+  /// Iterate through the current command list and dispatch commands. The list
+  /// should be cleared at the end of this operation.
+  ///
+  /// **NOTE**: This is not called directly by Ultralight-- you are expected to
+  ///           call this from your own implementation during drawing.
   ///
   virtual void DrawCommandList() = 0;
 };