Package eu.svjatoslav.sixth.e3d.renderer.raster.shapes.composite.base

Class AbstractCompositeShape

java.lang.Object
eu.svjatoslav.sixth.e3d.renderer.raster.shapes.AbstractShape
eu.svjatoslav.sixth.e3d.renderer.raster.shapes.composite.base.AbstractCompositeShape
Direct Known Subclasses:
BspCompositeShape, Graph, Grid2D, Grid3D, GuiComponent, LightSourceMarker, SolidPolygonArrow, SolidPolygonCone, SolidPolygonCylinder, SolidPolygonMesh, SolidPolygonPyramid, SolidPolygonRectangularBox, SolidPolygonSphere, TexturedRectangle, WireframeArrow, WireframeBox, WireframeCone, WireframeCylinder, WireframeDrawing, WireframePyramid, WireframeSphere
public class AbstractCompositeShape extends AbstractShape
A composite shape that groups multiple sub-shapes into a single logical unit.

Use AbstractCompositeShape to build complex 3D objects by combining primitive shapes (lines, polygons, textured polygons) into a group that can be positioned, rotated, and manipulated as one entity. Sub-shapes can be organized into named groups for selective visibility toggling.

Usage example - creating a custom composite shape:


 // Create a composite shape at position (0, 0, 200)
 AbstractCompositeShape myObject = new AbstractCompositeShape(
     new Point3D(0, 0, 200)
 );

 // Add sub-shapes
 myObject.addShape(new Line(
     new Point3D(-50, 0, 0), new Point3D(50, 0, 0),
     Color.RED, 2.0
 ));

 // Add shapes to a named group for toggling visibility
 myObject.addShape(labelShape, "labels");
 myObject.hideGroup("labels");  // hide all shapes in "labels" group
 myObject.showGroup("labels");  // show them again

 // Add to scene
 viewPanel.getRootShapeCollection().addShape(myObject);

Perspective-correct texturing:

Textured polygons are rendered with Quake-style perspective-correct scanline mapping (TexturedTriangle), so no screen-size tessellation is needed.

Extending this class:

Override beforeTransformHook(eu.svjatoslav.sixth.e3d.math.TransformStack, eu.svjatoslav.sixth.e3d.gui.RenderingContext) to customize shape appearance or behavior on each frame (e.g., animations, dynamic geometry updates).

See Also:

  • Constructor Details

    • AbstractCompositeShape

      public AbstractCompositeShape()
      Creates a composite shape at the world origin with no rotation.

    • AbstractCompositeShape

      public AbstractCompositeShape(Point3D location)
      Creates a composite shape at the specified location with no rotation.
      Parameters:
      location - the position in world space

    • AbstractCompositeShape

      public AbstractCompositeShape(Transform transform)
      Creates a composite shape with the specified transform (position and orientation).
      Parameters:
      transform - the initial transform defining position and rotation

  • Method Details

    • addShape

      public void addShape(AbstractShape shape)
      Adds a sub-shape to this composite shape without a group identifier.
      Parameters:
      shape - the shape to add

    • addShape

      public void addShape(AbstractShape shape, String groupId)
      Adds a sub-shape to this composite shape with an optional group identifier.

      Grouped shapes can be shown, hidden, or removed together using showGroup(java.lang.String), hideGroup(java.lang.String), and removeGroup(java.lang.String).

      Parameters:
      shape - the shape to add
      groupId - the group identifier, or null for ungrouped shapes

    • beforeTransformHook

      public void beforeTransformHook(TransformStack transformPipe, RenderingContext context)
      This method should be overridden by anyone wanting to customize the shape before it is rendered.
      Parameters:
      transformPipe - the current transform stack
      context - the rendering context for the current frame

    • getLocation

      public Point3D getLocation()
      Returns the world-space position of this composite shape.
      Returns:
      the translation component of this shape's transform

    • getBoundingBox

      public Box getBoundingBox()
      Returns the axis-aligned bounding box encompassing all sub-shapes.

      The bounding box is computed by aggregating the bounds of all visible sub-shapes, then transforming the result by this composite's own transform.

      Caching: The bounding box is recomputed whenever cacheNeedsRebuild is true (shapes added/removed/visibility changed). For nested composites, the bounds include their local transform offset.

      Overrides:
      getBoundingBox in class AbstractShape
      Returns:
      the axis-aligned bounding box in this composite's local coordinates

    • getSubShapesRegistry

      public List<SubShape> getSubShapesRegistry()
      Returns the sub-shapes registry (source of truth for all sub-shapes).

      This is the authoritative list of all sub-shapes including hidden ones. For per-frame rendering, use cachedRenderList instead (accessed internally).

      Returns:
      the registry list of all sub-shapes with their group and visibility metadata
      See Also:
      • the frame-optimized cache derived from this registry

    • extractSolidPolygons

      public List<SolidPolygon> extractSolidPolygons()
      Extracts all SolidPolygon instances from this composite shape.

      Recursively traverses the shape hierarchy and collects all SolidPolygon instances. Used for CSG operations where polygons are needed directly without conversion.

      Returns:
      list of SolidPolygon instances from this shape hierarchy

    • getViewSpaceTracker

      public ViewSpaceTracker getViewSpaceTracker()
      Returns the view-space tracker that monitors the distance and angle between the camera and this shape for level-of-detail adjustments.
      Returns:
      the view-space tracker for this shape

    • hideGroup

      public void hideGroup(String groupIdentifier)
      Hides all sub-shapes belonging to the specified group. Hidden shapes are not rendered but remain in the collection.
      Parameters:
      groupIdentifier - the group to hide
      See Also:

    • removeGroup

      public void removeGroup(String groupIdentifier)
      Permanently removes all sub-shapes belonging to the specified group.
      Parameters:
      groupIdentifier - the group to remove
      See Also:

    • getGroup

      public List<SubShape> getGroup(String groupIdentifier)
      Returns all sub-shapes belonging to the specified group.
      Parameters:
      groupIdentifier - the group identifier to match
      Returns:
      list of matching sub-shapes

    • setColor

      public void setColor(Color color)
      Paint solid elements of this composite shape into given color.

      Applies recursively to nested AbstractCompositeShape sub-shapes.

      Parameters:
      color - the color to apply to all solid sub-shapes

    • setGroupForUngrouped

      public void setGroupForUngrouped(String groupIdentifier)
      Assigns a group identifier to all sub-shapes that currently have no group.
      Parameters:
      groupIdentifier - the group to assign to ungrouped shapes

    • setMouseInteractionController

      public void setMouseInteractionController(MouseInteractionController mouseInteractionController)
      Description copied from class: AbstractShape
      Assigns a mouse interaction controller to this shape.

      Example usage:

      
 shape.setMouseInteractionController(new MouseInteractionController() {
     public boolean mouseClicked(int button) {
         System.out.println("Shape clicked!");
         return true;
     }
     public boolean mouseEntered() { return false; }
     public boolean mouseExited() { return false; }
 });
      Overrides:
      setMouseInteractionController in class AbstractShape
      Parameters:
      mouseInteractionController - the controller to handle mouse events, or null to disable mouse interaction

    • setRootComposite

      public void setRootComposite(boolean isRoot)
      Marks this composite as the root scene container.

      Called by ShapeCollection to configure its root composite.

      Parameters:
      isRoot - true if this is the root composite, false otherwise

    • getTransform

      public Transform getTransform()
      Returns this composite's transform (position and orientation).
      Returns:
      the transform object

    • setTransform

      public AbstractCompositeShape setTransform(Transform transform)
      Sets the transform for this composite shape.
      Parameters:
      transform - the new transform
      Returns:
      this composite shape (for chaining)

    • setCacheNeedsRebuild

      public void setCacheNeedsRebuild(boolean needsRebuild)
      Sets the cache rebuild flag on this composite and all nested composites recursively.

      Used by ShapeCollection to trigger a render-list rebuild when clearing the scene or for other advanced use cases.

      Parameters:
      needsRebuild - true to force cache rebuild on next frame

    • setShadingEnabled

      public AbstractCompositeShape setShadingEnabled(boolean shadingEnabled)
      Enables or disables shading for all SolidTriangle and SolidPolygon sub-shapes. When enabled, shapes use the global lighting manager from the rendering context to calculate flat shading based on light sources.

      Applies recursively to nested AbstractCompositeShape sub-shapes.

      Parameters:
      shadingEnabled - true to enable shading, false to disable
      Returns:
      this composite shape (for chaining)

    • setBackfaceCulling

      public AbstractCompositeShape setBackfaceCulling(boolean backfaceCulling)
      Enables or disables backface culling for all SolidPolygon and TexturedTriangle sub-shapes.

      Applies recursively to nested AbstractCompositeShape sub-shapes.

      Parameters:
      backfaceCulling - true to enable backface culling, false to disable
      Returns:
      this composite shape (for chaining)

    • union

      public void union(AbstractCompositeShape other)
      Performs an in-place union with another composite shape.

      This shape's SolidPolygon children are replaced with the union result. Non-SolidPolygon children from both shapes are preserved and combined.

      CSG Operation: Union combines two shapes into one, keeping all geometry from both. Uses BSP tree algorithms for robust boolean operations.

      Child handling:

      • SolidPolygon children from both shapes → replaced with union result
      • Non-SolidPolygon children from this shape → preserved
      • Non-SolidPolygon children from other shape → added to this shape
      • Nested AbstractCompositeShape children → preserved unchanged (not recursively processed)
      Parameters:
      other - the shape to union with
      See Also:

    • subtract

      public void subtract(AbstractCompositeShape other)
      Performs an in-place subtraction with another composite shape.

      This shape's SolidPolygon children are replaced with the difference result. The other shape acts as a "cutter" that carves out volume from this shape.

      CSG Operation: Subtract removes the volume of the second shape from the first shape. Useful for creating holes, cavities, and cutouts.

      Child handling:

      • SolidPolygon children from this shape → replaced with difference result
      • Non-SolidPolygon children from this shape → preserved
      • All children from other shape → discarded (other is just a cutter)
      • Nested AbstractCompositeShape children → preserved unchanged
      Parameters:
      other - the shape to subtract (the cutter)
      See Also:

    • intersect

      public void intersect(AbstractCompositeShape other)
      Performs an in-place intersection with another composite shape.

      This shape's SolidPolygon children are replaced with the intersection result. Only the overlapping volume between the two shapes remains.

      CSG Operation: Intersect keeps only the volume where both shapes overlap. Useful for creating shapes constrained by multiple boundaries.

      Child handling:

      • SolidPolygon children from this shape → replaced with intersection result
      • Non-SolidPolygon children from this shape → preserved
      • All children from other shape → discarded
      • Nested AbstractCompositeShape children → preserved unchanged
      Parameters:
      other - the shape to intersect with
      See Also:

    • showGroup

      public void showGroup(String groupIdentifier)
      Makes all sub-shapes belonging to the specified group visible.
      Parameters:
      groupIdentifier - the group to show
      See Also:

    • getGlobalRenderListVersion

      public static int getGlobalRenderListVersion()
      Returns the global render list version: incremented every time ANY composite's render list is rebuilt. Used by derived structures (BSP trees, GI scene snapshots) to detect that they must rebuild.
      Returns:
      monotonically increasing global version

    • collectRenderTriangles

      public void collectRenderTriangles(List<AbstractCoordinateShape> out)
      Collects the triangles of this composite's current render list, recursing into nested composites. These are the exact objects that get transformed and rendered: triangulated render-list polygons, or fragments (plain or lightmapped) for BspCompositeShape.

      Render lists are built lazily during transform; composites that have not been transformed yet (or are frustum-culled) contribute nothing. Vertices are in each composite's local space — callers combining several composites should require identity transforms.

      Parameters:
      out - list receiving the triangles

    • postprocessRenderList

      protected List<AbstractShape> postprocessRenderList(List<AbstractShape> renderList)
      Hook: post-processes the freshly rebuilt render list before it becomes the rendering cache. The default implementation returns the list unchanged. Subclasses may replace the list — e.g. BspCompositeShape compiles its polygons into BSP-ordered fragments here.
      Parameters:
      renderList - the render list built from the shape registry
      Returns:
      the render list to cache and render

    • transform

      public void transform(TransformStack transformPipe, RenderAggregator aggregator, RenderingContext context)
      Description copied from class: AbstractShape
      Transforms this shape from world space to screen space and queues it for rendering.

      This method is called once per frame for each shape in the scene. Implementations should apply the current transform stack to their vertices, compute screen-space coordinates, and if the shape is visible, add it to the RenderAggregator for depth-sorted painting.

      Specified by:
      transform in class AbstractShape
      Parameters:
      transformPipe - the current stack of transforms (world-to-camera transformations)
      aggregator - collects transformed shapes for depth-sorted rendering
      context - provides frame dimensions, graphics context, and frame metadata

    • getTransformWeight

      public int getTransformWeight(RenderingContext renderingContext)
      Total transform weight of this composite: the sum of its children's weights, i.e. roughly the number of leaf primitives below it. Computed lazily; recomputed only when this node's render list was rebuilt or the cache is older than WEIGHT_REFRESH_CYCLES cycles (children's internal rebuilds are picked up by the periodic refresh). Used solely for parallel fork load balancing, never for correctness, so brief staleness is harmless.

      Thread safety: a composite's fork decision runs on exactly one thread per cycle. Chunk-thread reads are cycle-stamped cache hits published through the executor's happens-before edge.

      Overrides:
      getTransformWeight in class AbstractShape
      Parameters:
      renderingContext - the rendering context (cycle identity)
      Returns:
      subtree transform weight, at least 1