Various opengl related comments

Author: emyfops

common/src/main/kotlin/com/lambda/graphics/buffer/Buffer.kt

@@ -179,10 +179,11 @@ abstract class Buffer(
     }
 
     /**
-     * Grows the backing buffers
+     * Allocates memory for each backing buffer using the specified size
      * This function handles the buffer binding
      *
      * @param size The size of the new buffer
+     * @return An [IllegalArgumentException] if validation fails; null if the allocation succeeds
      */
     open fun allocate(size: Long): Throwable? {
         if (!bufferValid(target, access))
@@ -203,9 +204,11 @@ abstract class Buffer(
     }
 
     /**
-     * Create a new buffer storage
+     * Allocates new storage for the OpenGL buffer using the provided data
      * This function cannot be called twice for the same buffer
      * This function handles the buffer binding
+     *
+     * @return [IllegalArgumentException] for an invalid target or usage; null if storage allocation is successful
      */
     open fun storage(data: ByteBuffer): Throwable? {
         if (!bufferValid(target, access))
@@ -226,11 +229,12 @@ abstract class Buffer(
     }
 
     /**
-     * Create a new buffer storage
+     * Allocates storage for the buffer object
      * This function cannot be called twice for the same buffer
      * This function handles the buffer binding
      *
      * @param size The size of the storage buffer
+     * @return [IllegalArgumentException] if the target or usage is invalid; null if storage allocation succeeds
      */
     open fun storage(size: Long): Throwable? {
         if (!bufferValid(target, access))
@@ -251,12 +255,12 @@ abstract class Buffer(
     }
 
     /**
-     * Maps all or part of a buffer object's data store into the client's address space
+     * Maps a specified region of the buffer's data store into client memory, processes it using the provided lambda, and then unmaps the buffer
      *
      * @param size      Specifies the length of the range to be mapped.
      * @param offset    Specifies the starting offset within the buffer of the range to be mapped.
      * @param block     Lambda scope with the mapped buffer passed in
-     * @return          Error encountered during the mapping process
+     * @return          [IllegalArgumentException] if there were errors during the validation, mapping or unmapping, null otherwise
      */
     open fun map(
         size: Long,
@@ -311,7 +315,9 @@ abstract class Buffer(
     }
 
     /**
-     * Sets the given data into the client mapped memory and executes the provided processing function to manage data transfer.
+     * Uploads the specified data to the buffer starting at the given offset
+     *
+     * This abstract function should be implemented to perform the actual data transfer into the buffer
      *
      * @param data      Data to set in memory
      * @param offset    The starting offset within the buffer of the range to be mapped

common/src/main/kotlin/com/lambda/graphics/gl/Matrices.kt

@@ -78,7 +78,7 @@ object Matrices {
     }
 
     /**
-     * Translates the current matrix by the given x, y, and z values.
+     * Applies a translation to the top matrix on the transformation stack
      *
      * @param x The translation amount along the X axis.
      * @param y The translation amount along the Y axis.
@@ -89,7 +89,7 @@ object Matrices {
     }
 
     /**
-     * Translates the current matrix by the given x, y, and z values.
+     * Applies a translation to the top matrix on the transformation stack
      *
      * @param x The translation amount along the X axis.
      * @param y The translation amount along the Y axis.
@@ -152,12 +152,10 @@ object Matrices {
     }
 
     /**
-     * Temporarily sets a vertex offset vector for the duration of a block.
+     * Applies a temporary vertex offset to mitigate precision issues in matrix operations on large coordinates
      *
-     * Use this to avoid precision loss when using matrices while being on huge coordinates.
-     *
-     * @param offset The transformation offset to apply to vertices.
-     * @param block The block of code to execute with the transformation applied.
+     * @param offset the offset to apply to vertices for reducing precision loss
+     * @param block the block of code within which the vertex offset is active
      */
     fun withVertexOffset(offset: Vec3d, block: () -> Unit) {
         vertexOffset = offset

common/src/main/kotlin/com/lambda/graphics/renderer/gui/font/FontRenderer.kt

@@ -46,7 +46,7 @@ object FontRenderer : AbstractGUIRenderer(VertexAttrib.Group.FONT, shader("font/
     private val gap get() = RenderSettings.gap * 0.5f - 0.8f
 
     /**
-     * Builds the vertex array for rendering the provided text string at a specified position.
+     * Renders a text string at a specified position with configurable color, scale, shadow, and emoji parsing
      *
      * @param text The text to render.
      * @param position The position to render the text.
@@ -75,6 +75,14 @@ object FontRenderer : AbstractGUIRenderer(VertexAttrib.Group.FONT, shader("font/
         }
     }
 
+    /**
+     * Renders a single glyph at the specified position with the given scale and color
+     *
+     * @param glyph The glyph information
+     * @param position The rendering position where the glyph will be drawn
+     * @param color The color of the glyph
+     * @param scale The scale factor of the glyph
+     */
     fun drawGlyph(
         glyph: GlyphInfo,
         position: Vec2d,
@@ -150,15 +158,18 @@ object FontRenderer : AbstractGUIRenderer(VertexAttrib.Group.FONT, shader("font/
     }
 
     /**
-     * Calculates the height of the text based on the specified scale.
+     * Computes the effective height of the rendered text
+     *
+     * The height is derived from the current font's base height, adjusted by a scaling factor
+     * that ensures consistent visual proportions
      *
      * @param scale The scale factor for the height calculation.
      * @return The height of the text at the specified scale.
      */
     fun getHeight(scale: Double = 1.0) = chars.height * getScaleFactor(scale) * 0.7
 
     /**
-     * Iterates over each character and emoji in the text and applies a block operation.
+     * Processes a text string by iterating over its characters and emojis, computing rendering positions, and invoking a block for each glyph
      *
      * @param text The text to iterate over.
      * @param color The color of the text.

common/src/main/kotlin/com/lambda/graphics/renderer/gui/font/core/LambdaEmoji.kt

@@ -25,11 +25,13 @@ enum class LambdaEmoji(val url: String) {
     private val emojiRegex = Regex(":[a-zA-Z0-9_]+:")
 
     /**
-     * Parses the emojis in the given text.
+     * Extracts emoji names from the provided text
      *
-     * @param text The text to parse.
+     * The function scans the input text for patterns matching emojis in the `:name:` format and
+     * returns a mutable list of the emoji names
      *
-     * @return A list of parsed strings that does not contain the colons
+     * @param text The text to parse.
+     * @return A list of extract emoji names
      */
     fun parse(text: String): MutableList<String> =
         emojiRegex.findAll(text).map { it.value }.toMutableList()

common/src/main/kotlin/com/lambda/graphics/texture/Texture.kt

@@ -75,22 +75,23 @@ open class Texture {
     var height = -1; protected set
 
     /**
-     * Binds the texture to a specific slot in the graphics pipeline.
+     * Binds this texture to the specified slot in the graphics pipeline
      */
     open fun bind(slot: Int = 0) {
         bindTexture(id, slot)
     }
 
     /**
-     * Unbinds the currently bound texture
+     * Unbinds any texture from the specified slot
      */
     open fun unbind(slot: Int = 0) {
         bindTexture(0, slot)
     }
 
     /**
      * Uploads an image to the texture and generates mipmaps for the texture if applicable
-     * This function does not bind the texture
+     *
+     * Note that the texture must be bound before calling this function
      *
      * @param image     The image to upload to the texture
      * @param offset    The mipmap level to upload the image to
@@ -112,7 +113,8 @@ open class Texture {
 
     /**
      * Uploads an image to the texture and generates mipmaps for the texture if applicable
-     * This function does not bind the texture
+     *
+     * Note that the texture must be bound before calling this function
      *
      * @param buffer    The image buffer to upload to the texture
      * @param width     The width of the texture
@@ -136,7 +138,8 @@ open class Texture {
 
     /**
      * Updates the data of a texture
-     * This function does not bind the texture
+     *
+     * Note that the texture must be bound before calling this function
      *
      * @param image     The image to upload to the texture
      * @param offset    The mipmap level to upload the image to

common/src/main/kotlin/com/lambda/graphics/texture/TextureOwner.kt

@@ -34,7 +34,7 @@ object TextureOwner {
         get() = textureMap.getValue(this@texture)[0]
 
     /**
-     * Retrieves a specific texture owned by the object by its index
+     * Retrieves the texture associated with the receiver object at the specified index
      *
      * @param index The index of the texture to retrieve
      * @return The texture [T] at the given index