kaze/orx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[orx-mesh] Add generated and verified documentation

Browse Source
This commit is contained in:
Edwin Jakobs
2025-01-24 20:48:21 +01:00
parent 3073e88875
commit 023b52a4fc
12 changed files with 405 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
orx-mesh/src/commonMain/kotlin/CompoundMeshData.kt
View File

@@ -1,7 +1,12 @@
package org.openrndr.extra.mesh
/**
* Compound mesh data interface
* Represents a compound mesh data structure that combines multiple meshes and their associated vertex data.
*
* This interface is used to handle scenarios where a collection of meshes, grouped under named compounds,
* is operated upon as a single entity. Common operations include combining the meshes into a single one or
* refining them into triangular meshes.
*/
interface ICompoundMeshData {
val vertexData: IVertexData
@@ -12,6 +17,16 @@ interface ICompoundMeshData {
fun toMeshData(): IMeshData
}
/**
* Represents a compound mesh data structure containing multiple named sub-meshes
* and their associated shared vertex data. This class allows manipulation of
* grouped meshes as a single entity and provides methods for operations like
* triangulation and converting the meshes to a single data structure.
*
* @property vertexData The shared vertex data associated with the compound meshes.
* @property compounds A map of named sub-meshes where the key represents the compound name
* and the value represents the corresponding mesh data.
*/
class CompoundMeshData(
override val vertexData: VertexData,
override val compounds: Map<String, MeshData>
@@ -28,6 +43,15 @@ class CompoundMeshData(
}
}
/**
* A mutable implementation of a compound mesh data structure, combining vertex data and a set of named mesh compounds.
*
* This class allows the manipulation of multiple meshes grouped under named compounds, while sharing a common
* vertex data structure. It supports operations such as triangulation and conversion to a unified mesh representation.
*
* @property vertexData The mutable vertex data shared across the compound meshes.
* @property compounds A mutable mapping of compound names to their associated mutable mesh data.
*/
class MutableCompoundMeshData(
override val vertexData: MutableVertexData,
override val compounds: MutableMap<String, MutableMeshData>

21
orx-mesh/src/commonMain/kotlin/CompoundMeshDataExtensions.kt
View File

@@ -3,8 +3,16 @@ package org.openrndr.extra.mesh
import org.openrndr.draw.VertexBuffer
import org.openrndr.draw.vertexBuffer
/**
* Write compound mesh data to [VertexBuffer]
* Converts the compound mesh data into a single [VertexBuffer] for rendering.
*
* The method internally triangulates the compound mesh data, calculates the total number
* of triangles contained within the mesh data, and populates a [VertexBuffer] with
* the vertex attributes (e.g., positions, normals, texture coordinates, etc.) required
* for rendering the mesh.
*
* @return a [VertexBuffer] containing the vertex data of the triangulated mesh.
*/
fun ICompoundMeshData.toVertexBuffer(): VertexBuffer {
val triangulated = this.triangulate()
@@ -22,8 +30,17 @@ fun ICompoundMeshData.toVertexBuffer(): VertexBuffer {
return vertexBuffer
}
/**
* Convert compound mesh data to [IPolygon] compounds
* Converts the compound mesh data into a map of polygons grouped by their compound names.
*
* This function traverses the `compounds` map within the `ICompoundMeshData` instance,
* converting each `IMeshData` to a list of `IPolygon` objects. The resulting map preserves
* the structure of the original `compounds` map, associating each compound name with its
* corresponding list of polygons.
*
* @return a map where each key is the name of a compound, and the value is a list of [IPolygon]
* representing the polygons of the corresponding compound data.
*/
fun ICompoundMeshData.toPolygons(): Map<String, List<IPolygon>> {
return compounds.mapValues { it.value.toPolygons() }

87
orx-mesh/src/commonMain/kotlin/IndexedPolygon.kt
View File

@@ -6,8 +6,10 @@ import org.openrndr.math.Vector3
import org.openrndr.math.Vector4
import kotlin.math.*
/**
* Indexed polygon interface
* Represents an indexed polygon in 3D space. The polygon is defined using indices referencing
* the various attributes (e.g., position, texture coordinates, normals) provided in an external vertex data.
*/
interface IIndexedPolygon {
/**
@@ -53,10 +55,13 @@ interface IIndexedPolygon {
)
}
/**
* Determine if polygon is planar
* @param vertexData the vertex data
* @param eps error tolerance
* Checks if the polygon defined by the given vertex data is planar.
*
* @param vertexData The vertex data that contains the positions of the polygon's vertices.
* @param eps A small tolerance value used to determine planarity. Defaults to 1E-2.
* @return True if the polygon is planar, false otherwise.
*/
fun isPlanar(vertexData: IVertexData, eps: Double = 1E-2): Boolean {
fun normal(i: Int): Vector3 {
@@ -76,8 +81,12 @@ interface IIndexedPolygon {
}
}
/**
* Determine polygon convexity
* Determines if the polygon defined by the given vertex data is convex.
*
* @param vertexData The vertex data containing the positions of the polygon's vertices.
* @return True if the polygon is convex, false otherwise.
*/
fun isConvex(vertexData: IVertexData): Boolean {
val planar = base(vertexData).inversed
@@ -130,8 +139,15 @@ interface IIndexedPolygon {
return abs(round(angleSum / (2 * PI))) == 1.0
}
/**
* Evaluate polygon normal
* Computes the normal vector of the polygon based on the given vertex data.
*
* The method calculates the cross product of two edges of the polygon
* and normalizes the resulting vector to obtain the normal.
*
* @param vertexData The vertex data that contains the positions of the polygon's vertices.
* @return A normalized 3D vector representing the normal of the polygon.
*/
fun normal(vertexData: IVertexData) : Vector3 {
val u = vertexData.positions[positions[1]] - vertexData.positions[positions[0]]
@@ -139,15 +155,28 @@ interface IIndexedPolygon {
return u.cross(v).normalized
}
/**
* Convert to [IPolygon]
* @param vertexData the vertex data required to build the [IPolygon]
* Converts the provided vertex data into a polygon representation.
*
* @param vertexData The vertex data containing positions, normals, texture coordinates, and other attributes of the vertices.
* @return A polygon created from the given vertex data.
*/
fun toPolygon(vertexData: IVertexData): IPolygon
}
/**
* Immutable indexed polygon implementation
* Represents a polygon defined by indices corresponding to vertex data such as positions,
* texture coordinates, colors, normals, tangents, and bitangents. It can be used to describe
* a geometric shape for rendering or processing in 3D graphics or geometry applications.
*
* @property positions List of indices referencing the vertex positions.
* @property textureCoords List of indices referencing the texture coordinates.
* @property colors List of indices referencing vertex colors.
* @property normals List of indices referencing vertex normals.
* @property tangents List of indices referencing vertex tangents.
* @property bitangents List of indices referencing vertex bitangents.
*/
data class IndexedPolygon(
override val positions: List<Int>,
@@ -175,10 +204,14 @@ data class IndexedPolygon(
}
}
/**
* Convert to a list of triangle [IndexedPolygon]
* Triangulates the polygon represented by the provided vertex data.
*
* Supports non-planar and non-convex polygons
* @param vertexData The vertex data that defines the positions, texture coordinates,
* colors, normals, tangents, and bitangents of the polygon vertices.
* @return A list of indexed triangles representing the triangulated polygon. Each triangle
* is defined using the vertex information from the provided vertex data.
*/
fun triangulate(vertexData: IVertexData): List<IndexedPolygon> {
return when {
@@ -232,15 +265,18 @@ data class IndexedPolygon(
)
}
/**
* Shift indices
* @param positions position index shift
* @param textureCoords texture coordinate index shift
* @param colors color index shift
* @param normals normal index shift
* @param tangents tangent index shift
* @param bitangents bitangent index shift
* Shifts the indices for position, texture coordinates, colors, normals, tangents, and bitangents
* by the specified amounts and returns a new IndexedPolygon with the updated indices.
*
* @param positions The amount to shift the position indices. Defaults to 0.
* @param textureCoords The amount to shift the texture coordinate indices. Defaults to 0.
* @param colors The amount to shift the color indices. Defaults to 0.
* @param normals The amount to shift the normal indices. Defaults to 0.
* @param tangents The amount to shift the tangent indices. Defaults to 0.
* @param bitangents The amount to shift the bitangent indices. Defaults to 0.
* @return A new IndexedPolygon with indices shifted by the provided values.
*/
fun shiftIndices(
positions: Int = 0,
@@ -261,8 +297,21 @@ data class IndexedPolygon(
}
}
/**
* Mutable indexed polygon implementation
* Represents a mutable 3D indexed polygon. This class allows modifications to its indices and
* provides functionality to transform vertex references into a corresponding polygon representation.
*
* The polygon is defined by indices referencing an external vertex data source, such as the
* position, texture coordinates, normals, colors, tangents, and bitangents of the vertices. These
* indices can be updated, providing flexibility for dynamic operations on the polygon.
*
* @property positions Mutable list of position indices defining the polygon's vertices.
* @property textureCoords Mutable list of texture coordinate indices defining the mapping of textures.
* @property normals Mutable list of normal indices, which specify the normals of the vertices.
* @property colors Mutable list of color indices specifying the vertex colors.
* @property tangents Mutable list of tangent indices, optional.
* @property bitangents Mutable list of bitangent indices, optional.
*/
data class MutableIndexedPolygon(
override val positions: MutableList<Int>,

16
orx-mesh/src/commonMain/kotlin/IndexedPolygonExtensions.kt
View File

@@ -10,10 +10,14 @@ internal fun <T : LinearType<T>> bc(barycentric: Vector3, items: List<T>): T {
return (items[0] * barycentric.x) + (items[1] * barycentric.y) + (items[2] * barycentric.z)
}
/**
* Evaluate a point in triangle
* @param vertexData the vertex data to use
* @param barycentric the barycentric coordinates of the point to evaluate
* Computes a `Point` by interpolating vertex attributes from a 3D polygon using
* barycentric coordinates.
*
* @param vertexData The vertex data containing positions, texture coordinates, colors, normals, tangents, and bitangents.
* @param barycentric The barycentric coordinates used to interpolate the vertex attributes.
* @return A `Point` containing interpolated vertex attributes including position, texture coordinates, color, normal, tangent, and bitangent.
*/
fun IIndexedPolygon.point(vertexData: VertexData, barycentric: Vector3): Point {
require(positions.size == 3)
@@ -35,8 +39,12 @@ fun IIndexedPolygon.point(vertexData: VertexData, barycentric: Vector3): Point {
)
}
/**
* Evaluate position bounds
* Calculates the bounding box of a list of indexed polygons using the specified vertex data.
*
* @param vertexData The vertex data containing the positions of the vertices referenced by the polygons.
* @return A [Box] representing the axis-aligned bounding box of the polygons. If the list is empty, returns an empty box.
*/
fun List<IIndexedPolygon>.bounds(vertexData: IVertexData): Box {
if (isEmpty()) {

82
orx-mesh/src/commonMain/kotlin/MeshData.kt
View File

@@ -2,36 +2,102 @@ package org.openrndr.extra.mesh
import kotlin.jvm.JvmRecord
/**
* Mesh data interface
* Interface representing mesh data in 3D space.
*
* Provides access to vertices and polygonal structure, along with methods
* for common mesh transformations and manipulations.
*/
interface IMeshData {
/**
* Provides vertex data for the mesh, including positions, normals, colors,
* texture coordinates, tangents, and bitangents. This data is central to
* defining the geometric and visual properties of the mesh and can be used
* for performing various operations and transformations.
*/
val vertexData: IVertexData
/**
* Represents the list of indexed polygons that define the structure of the mesh.
*
* Each polygon in the list is an instance of [IIndexedPolygon], which references
* vertex attributes through indices, such as positions, texture coordinates, normals, and more.
*/
val polygons: List<IIndexedPolygon>
/**
* Convert mesh data to triangular mesh data
* Converts the current mesh data into a fully triangulated form.
*
* This method processes the mesh's polygons and ensures that all non-triangle polygons
* are subdivided into triangles. The resulting mesh maintains the original structure
* and attributes while adhering to the requirement of being composed solely of triangles.
*
* @return A new instance of [IMeshData] containing the triangulated representation
* of the original mesh data.
*/
fun triangulate(): IMeshData
/**
* Convert mesh data to a list of [IPolygon]
* Converts the current mesh data into a list of polygons.
*
* This method extracts the polygonal structure of the mesh and represents
* it as a collection of [IPolygon] instances. Each polygon contains vertex
* data such as positions, texture coordinates, colors, normals, tangents,
* and bitangents, which are used to define its geometry and visual properties.
*
* @return A list of [IPolygon] instances representing the individual polygons
* within the mesh.
*/
fun toPolygons(): List<IPolygon>
/**
* Join mesh data with [other] mesh data
* Combines the current mesh data with another mesh data instance.
*
* The method merges the polygons and vertex attributes of the two meshes, resulting in a new
* mesh data instance that includes the data from both inputs.
*
* @param other The [IMeshData] instance to be merged with the current mesh data.
* @return A new [IMeshData] instance that contains the combined data from both meshes.
*/
fun join(other: IMeshData): IMeshData
/**
* Converts the current mesh data into an immutable `MeshData` instance.
*
* This method provides a direct representation of the current mesh,
* encapsulating its vertex data and polygon information in an immutable format.
*
* @return A `MeshData` instance representing the current mesh data.
*/
fun toMeshData(): MeshData
/**
* Converts the current mesh data into a mutable representation.
*
* This method provides a `MutableMeshData` instance that encapsulates
* the current mesh data, allowing modifications to its vertex and polygon
* structures. The mutable representation is useful for scenarios where
* changes to the mesh data are required, such as editing geometry or
* updating attributes.
*
* @return A `MutableMeshData` instance that represents the current mesh
* data in a mutable format.
*/
fun toMutableMeshData() : MutableMeshData
}
/**
* Immutable mesh data implementation
* Represents data for a 3D mesh. Implements the `IMeshData` interface and provides additional methods
* for manipulating and combining mesh data. This class is immutable and includes operations for
* triangulation, conversion to polygons, and joining multiple meshes.
*
* @property vertexData The vertex data associated with the mesh, including positions, normals, tangents,
* texture coordinates, colors, and bitangents.
* @property polygons A list of polygons defined using indexed vertex data.
*/
@JvmRecord
data class MeshData(
@@ -142,7 +208,11 @@ data class MeshData(
/**
* Mutable mesh data implementation
* Represents mutable mesh data with modifiable vertex data and polygonal structure.
*
* @property vertexData Mutable vertex data instance containing positions, texture coordinates,
* colors, normals, tangents, and bitangents of vertices.
* @property polygons Mutable list of indexed polygons defining the geometric structure of the mesh.
*/
data class MutableMeshData(
override val vertexData: MutableVertexData,

64
orx-mesh/src/commonMain/kotlin/MeshDataExtensions.kt
View File

@@ -6,7 +6,15 @@ import org.openrndr.math.*
import org.openrndr.shape.Box
/**
* The [VertexFormat] for a [VertexBuffer] with positions, normals and texture coordinates.
* Defines the vertex format for 3D objects with attributes including positions, normals,
* texture coordinates, and colors. This format specifies the structure of vertex data
* to be used for rendering 3D objects.
*
* - The `position` attribute represents the 3D position of each vertex, using 3 components (x, y, z).
* - The `normal` attribute defines the normal vector at each vertex, using 3 components (x, y, z),
* which is essential for lighting calculations.
* - The `textureCoordinate` attribute provides 2D texture mapping coordinates (u, v) for each vertex.
* - The `color` attribute specifies a color for each vertex, using 4 components (r, g, b, a).
*/
internal val objVertexFormat = vertexFormat {
position(3)
@@ -15,6 +23,19 @@ internal val objVertexFormat = vertexFormat {
color(4)
}
/**
* Represents a vertex format definition that includes attributes necessary
* for 3D rendering with tangents and bitangents, commonly used for advanced lighting
* techniques such as normal mapping.
*
* This vertex format includes the following attributes:
* - Position: 3D coordinates (Vector3).
* - Normal: 3D vector for surface orientation (Vector3).
* - Texture Coordinate: 2D UV coordinate (Vector2).
* - Color: RGBA color values (Vector4).
* - Tangent: 3D vector for tangent space (Vector3).
* - Bitangent: 3D vector perpendicular to tangent and normal vectors (Vector3).
*/
internal val objVertexFormatTangents = vertexFormat {
position(3)
normal(3)
@@ -26,14 +47,29 @@ internal val objVertexFormatTangents = vertexFormat {
/**
* Determine if [IMeshData] is triangular by checking if each polygon has exactly 3 vertices
* Checks if all polygons in the mesh are triangular.
*
* This method evaluates each polygon to determine whether it consists
* of exactly three vertices. A mesh is considered triangular if all its
* polygons meet this condition.
*
* @return True if all polygons in the mesh are triangles, false otherwise.
*/
fun IMeshData.isTriangular(): Boolean {
return polygons.all { it.positions.size == 3 }
}
/**
* Convert a [MeshData] instance into a [VertexBuffer]
* Converts the current mesh data into a [VertexBuffer] representation, preparing geometry for rendering.
*
* The method processes the mesh data, including positions, normals, texture coordinates, colors, tangents,
* and bitangents, and writes it into a vertex buffer. It uses triangulated geometry to ensure compatibility
* with rendering pipelines that expect triangles as input.
*
* @param elementOffset The starting offset in the vertex buffer where the mesh data should be written. Defaults to 0.
* @param vertexBuffer An optional pre-existing [VertexBuffer] in which to store the data. If not provided, a new
* [VertexBuffer] is created with the appropriate format.
* @return A [VertexBuffer] containing the mesh data in the specified format, ready for rendering.
*/
fun IMeshData.toVertexBuffer(elementOffset: Int = 0, vertexBuffer: VertexBuffer? = null): VertexBuffer {
val objects = triangulate().toPolygons()
@@ -78,8 +114,17 @@ fun IMeshData.toVertexBuffer(elementOffset: Int = 0, vertexBuffer: VertexBuffer?
}
/**
* Weld vertices
* @param positionFractBits number of bits to use for fractional representation, negative amount to skip welding
* Welds the mesh data by consolidating vertices based on specified fractional bit precision
* for attributes such as positions, texture coordinates, colors, normals, tangents, and bitangents.
* This reduces redundant vertices and optimizes the mesh structure.
*
* @param positionFractBits The number of fractional bits to use for quantizing vertex positions. If negative, positions are not modified.
* @param textureCoordFractBits The number of fractional bits to use for quantizing texture coordinates. If negative, texture coordinates are not modified.
* @param colorFractBits The number of fractional bits to use for quantizing vertex colors. If negative, colors are not modified.
* @param normalFractBits The number of fractional bits to use for quantizing vertex normals. If negative, normals are not modified.
* @param tangentFractBits The number of fractional bits to use for quantizing vertex tangents. If negative, tangents are not modified.
* @param bitangentFractBits The number of fractional bits to use for quantizing vertex bitangents. If negative, bitangents are not modified.
* @return A new instance of MeshData containing the welded and optimized vertex data and polygons.
*/
fun IMeshData.weld(
positionFractBits: Int,
@@ -229,7 +274,14 @@ fun IMeshData.weld(
}
/**
* Evaluate mesh bounds
* Provides the bounding box of the mesh based on its polygons and associated vertex data.
*
* The bounding box is an axis-aligned box that encapsulates all the polygons in the mesh.
* It is computed using the positions in the mesh's vertex data referenced by the polygons.
* If the mesh contains no polygons, an empty bounding box is returned.
*
* @receiver The [IMeshData] instance for which the bounding box is calculated.
* @return A [Box] representing the axis-aligned bounding box of the mesh.
*/
val IMeshData.bounds: Box
get() = polygons.bounds(vertexData)

16
orx-mesh/src/commonMain/kotlin/Point.kt
View File

@@ -5,13 +5,15 @@ import org.openrndr.math.Vector2
import org.openrndr.math.Vector3
/**
* Point with optional attributes
* @param position position attribute
* @param textureCoord optional texture coordinate attribute
* @param color optional color attribute
* @param normal optional normal attribute
* @param tangent optional tangent attribute
* @param bitangent optional bitangent attribute
* Represents a 3D point with optional attributes for texture coordinates, color,
* normal vector, tangent vector, and bitangent vector.
*
* @property position The 3D position of the point represented as a [Vector3].
* @property textureCoord The optional 2D texture coordinates of the point represented as a [Vector2].
* @property color The optional color of the point represented as a [ColorRGBa].
* @property normal The optional normal vector of the point represented as a [Vector3].
* @property tangent The optional tangent vector of the point represented as a [Vector3].
* @property bitangent The optional bitangent vector of the point represented as a [Vector3].
*/
data class Point(
val position: Vector3,

50
orx-mesh/src/commonMain/kotlin/Polygon.kt
View File

@@ -10,7 +10,15 @@ import kotlin.math.min
/**
* 3D Polygon interface
* Represents a polygon in 3D space, defined by a collection of attributes such as positions, texture coordinates,
* colors, normals, tangents, and bitangents.
*
* @property positions The list of 3D positions of the polygon vertices represented as [Vector3].
* @property textureCoords The list of 2D texture coordinates for the polygon vertices represented as [Vector2].
* @property colors The list of color values for the polygon vertices represented as [ColorRGBa].
* @property normals The list of normal vectors for the polygon vertices represented as [Vector3].
* @property tangents The list of tangent vectors for the polygon vertices represented as [Vector3].
* @property bitangents The list of bitangent vectors for the polygon vertices represented as [Vector3].
*/
interface IPolygon {
val positions: List<Vector3>
@@ -20,16 +28,27 @@ interface IPolygon {
val tangents: List<Vector3>
val bitangents: List<Vector3>
/**
* Transforms the polygon using a given 4x4 transformation matrix.
*
* @param t The 4x4 transformation matrix to apply to the polygon.
* @return A new polygon instance resulting from applying the transformation.
*/
fun transform(t: Matrix44): IPolygon
}
/**
* Immutable 3D Polygon implementation
* Represents a polygon in 3D space with immutable attributes such as positions, texture coordinates,
* colors, normals, tangents, and bitangents. Provides methods to transform the polygon and convert
* it to a mutable version.
*
* @property positions Vertex 3D positions
* @property normals Vertex 3D normals
* @property textureCoords Vertex 2D texture coordinates
* @constructor Create empty 3D Polygon
* @constructor Creates a Polygon with specified attributes.
* @param positions The list of 3D positions of the polygon vertices.
* @param textureCoords The list of 2D texture coordinates for the polygon vertices.
* @param colors The list of color values for the polygon vertices.
* @param normals The list of normal vectors for the polygon vertices.
* @param tangents The list of tangent vectors for the polygon vertices.
* @param bitangents The list of bitangent vectors for the polygon vertices.
*/
class Polygon(
override val positions: List<Vector3> = emptyList(),
@@ -44,7 +63,10 @@ class Polygon(
}
/**
* Create a [MutablePolygon] by copying
* Converts the current immutable polygon instance into a mutable polygon.
*
* @return A [MutablePolygon] instance containing mutable lists of positions, texture coordinates,
* colors, normals, tangents, and bitangents copied from the current polygon.
*/
fun toMutablePolygon(): MutablePolygon {
return MutablePolygon(
@@ -59,7 +81,19 @@ class Polygon(
}
/**
* Mutable 3D Polygon implementation
* A mutable implementation of the [IPolygon] interface that represents a polygon in 3D space.
* This class allows modification of the polygon's attributes such as vertex positions,
* texture coordinates, colors, normals, tangents, and bitangents.
*
* @constructor Creates a mutable polygon with optional initial values for positions, texture coordinates,
* colors, normals, tangents, and bitangents. If no initial values are provided, empty mutable lists are used.
*
* @property positions The mutable list of 3D positions of the polygon vertices, represented as [Vector3].
* @property textureCoords The mutable list of 2D texture coordinates for the polygon vertices, represented as [Vector2].
* @property colors The mutable list of color values for the polygon vertices, represented as [ColorRGBa].
* @property normals The mutable list of normal vectors for the polygon vertices, represented as [Vector3].
* @property tangents The mutable list of tangent vectors for the polygon vertices, represented as [Vector3].
* @property bitangents The mutable list of bitangent vectors for the polygon vertices, represented as [Vector3].
*/
class MutablePolygon(
override val positions: MutableList<Vector3> = mutableListOf(),

62
orx-mesh/src/commonMain/kotlin/VertexData.kt
View File

@@ -5,7 +5,9 @@ import org.openrndr.math.Vector2
import org.openrndr.math.Vector3
/**
* Vertex data interface
* Interface representing vertex data for 3D graphics. This includes attributes such as positions,
* texture coordinates, colors, normals, tangents, and bitangents. It provides methods to convert
* the data to either immutable or mutable vertex data representations.
*/
interface IVertexData {
/**
@@ -39,18 +41,35 @@ interface IVertexData {
val bitangents: List<Vector3>
/**
* Convert to [VertexData]
* Converts the vertex data represented by the current instance into an immutable [VertexData] object.
* This includes attributes such as positions, texture coordinates, colors, normals, tangents, and bitangents.
*
* @return A [VertexData] instance containing the immutable representation of the vertex data.
*/
fun toVertexData() : VertexData
/**
* Convert to [MutableVertexData]
* Converts the vertex data represented by the current instance into a mutable [MutableVertexData] object.
* This includes attributes such as positions, texture coordinates, colors, normals, tangents, and bitangents.
*
* @return A [MutableVertexData] instance containing the mutable representation of the vertex data.
*/
fun toMutableVertexData() : MutableVertexData
}
/**
* Immutable vertex data implementation
* Immutable implementation of vertex data for 3D graphics. This class provides a container for
* vertex attributes such as positions, texture coordinates, colors, normals, tangents, and bitangents.
*
* It implements the [IVertexData] interface, allowing easy conversion between immutable and mutable
* representations of vertex data.
*
* @property positions List of vertex positions as [Vector3].
* @property textureCoords List of 2D texture coordinates as [Vector2].
* @property colors List of vertex colors as [ColorRGBa].
* @property normals List of vertex normals as [Vector3].
* @property tangents List of vertex tangents as [Vector3].
* @property bitangents List of vertex bitangents as [Vector3].
*/
class VertexData(
override val positions: List<Vector3> = emptyList(),
@@ -75,7 +94,22 @@ class VertexData(
/**
* Mutable vertex data implementation
* Mutable implementation of vertex data for 3D graphics. This class provides a container for
* vertex attributes such as positions, texture coordinates, colors, normals, tangents, and bitangents
* with mutable backing lists. It allows modification of vertex data.
*
* This class implements the [IVertexData] interface, enabling conversion between mutable and immutable
* representations of vertex data.
*
* @constructor Creates a [MutableVertexData] object with optional initial data provided as mutable lists
* for positions, texture coordinates, colors, normals, tangents, and bitangents.
*
* @property positions Mutable list of vertex positions as [Vector3].
* @property textureCoords Mutable list of 2D texture coordinates as [Vector2].
* @property colors Mutable list of vertex colors as [ColorRGBa].
* @property normals Mutable list of vertex normals as [Vector3].
* @property tangents Mutable list of vertex tangents as [Vector3].
* @property bitangents Mutable list of vertex bitangents as [Vector3].
*/
class MutableVertexData(
override val positions: MutableList<Vector3> = mutableListOf(),
@@ -99,7 +133,11 @@ class MutableVertexData(
}
/**
* Add [point] to vertex data
* Adds a [Point] to the vertex data by updating the corresponding mutable lists of vertex attributes.
* Each optional attribute of the point is only added if it is not null.
*
* @param point The 3D point to be added, which may include optional attributes such as texture coordinates,
* color, normal, tangent, and bitangent.
*/
fun MutableVertexData.add(point: Point) {
positions.add(point.position)
@@ -111,7 +149,17 @@ fun MutableVertexData.add(point: Point) {
}
/**
* Retrieve [Point] from vertex data
* Retrieves a [Point] instance from the vertex data at the specified indices.
* The indices allow access to positions, texture coordinates, colors, normals,
* tangents, and bitangents.
*
* @param index The index for retrieving the vertex position.
* @param textureCoordsIndex The index for retrieving texture coordinates. Defaults to the value of `index`.
* @param colorsIndex The index for retrieving vertex colors. Defaults to the value of `index`.
* @param normalsIndex The index for retrieving vertex normals. Defaults to the value of `index`.
* @param tangentsIndex The index for retrieving vertex tangents. Defaults to the value of `index`.
* @param bitangentsIndex The index for retrieving vertex bitangents. Defaults to the value of `index`.
* @return A [Point] object containing the vertex attributes at the specified indices.
*/
operator fun IVertexData.get(
index: Int,

21
orx-mesh/src/commonMain/kotlin/VertexDataExtensions.kt
View File

@@ -7,7 +7,16 @@ import org.openrndr.math.Vector2
import org.openrndr.math.Vector3
/**
* Convert vertex data to [VertexBuffer]. Assumes every 3 consecutive vertices encode a triangle.
* Converts the vertex data stored in the [IVertexData] instance to a [VertexBuffer].
* The method iterates through the vertex attributes such as positions, normals, texture coordinates,
* and colors, and writes them sequentially into the provided or newly created [VertexBuffer].
* Missing attributes are substituted with default values.
*
* @param elementOffset The index offset where the vertex data should start being written in the buffer.
* Defaults to 0 if no offset is specified.
* @param vertexBuffer An optional existing [VertexBuffer] instance to be reused. If null, a new buffer
* will be created.
* @return A [VertexBuffer] containing the processed vertex data.
*/
fun IVertexData.toVertexBuffer(elementOffset: Int = 0, vertexBuffer: VertexBuffer? = null): VertexBuffer {
@@ -43,7 +52,15 @@ fun IVertexData.toVertexBuffer(elementOffset: Int = 0, vertexBuffer: VertexBuffe
}
/**
* Convert vertex data to [MeshData]. Assumes every 3 consecutive vertices encode a triangle.
* Converts the vertex data into a MeshData representation by constructing the indexed polygons
* based on the vertex data attributes such as positions, texture coordinates, colors, normals,
* tangents, and bitangents.
*
* Each triangle in the vertex data is represented as an IndexedPolygon, where the indices are
* generated based on the triangle order, and optional attributes like texture coordinates or
* colors are included if present in the source vertex data.
*
* @return A MeshData instance containing the vertex data and a list of indexed polygons representing the mesh.
*/
fun VertexData.toMeshData(): MeshData {

19
orx-mesh/src/commonMain/kotlin/Wireframe.kt
View File

@@ -3,14 +3,29 @@ package org.openrndr.extra.mesh
import org.openrndr.math.Vector3
/**
* Extract wireframe from mesh data
* Generates a wireframe representation of the mesh.
*
* This method processes the polygons of the mesh data and extracts the vertex positions
* for each polygon. The result is a list of lists, where each inner list represents the
* positions of the vertices forming the edges of a polygon in 3D space.
*
* @return A list of lists of [Vector3], where each inner list contains the vertex positions
* that form the edges of a polygon, effectively representing the wireframe of the mesh.
*/
fun IMeshData.wireframe(): List<List<Vector3>> {
return polygons.map { ip -> ip.toPolygon(this.vertexData).positions.toList() }
}
/**
* Extract wireframe from compound mesh data
* Generates a wireframe representation of the compound mesh data.
*
* This method aggregates the wireframe representations of all meshes within the compounds
* of the compound mesh data. Each compound's mesh is processed to extract its wireframe
* as a list of edges represented by vertex positions in 3D space.
*
* @return A list of lists of [Vector3], where each inner list represents the vertex positions
* forming the edges of a polygon. This effectively provides the wireframe data
* for the entire compound mesh.
*/
fun ICompoundMeshData.wireframe(): List<List<Vector3>> {
return compounds.values.flatMap { it.wireframe() }

6
orx-mesh/src/jvmMain/kotlin/VertexBufferExtensions.kt
View File

@@ -30,7 +30,11 @@ private fun ByteBuffer.getColorRGBa(): ColorRGBa {
}
/**
Convert vertex buffer contents to a list of [Polygon] instances
* Converts the vertex buffer into a list of polygons based on the provided vertex count.
* Each polygon is formed by grouping vertices into triangles.
*
* @param vertexCount The number of vertices to process from the vertex buffer. Defaults to the total number of vertices in the buffer.
* @return A list of polygons, where each polygon contains the vertex positions, texture coordinates, colors, and normals.
*/
fun VertexBuffer.toPolygons(vertexCount: Int = this.vertexCount): List<Polygon> {
require(vertexFormat == objVertexFormat)