[sixth-3d.git] /

/*
 * Sixth 3D engine. Author: Svjatoslav Agejenko.
 * This project is released under Creative Commons Zero (CC0) license.
 */
package eu.svjatoslav.sixth.e3d.renderer.raster.shapes.composite.base;

import eu.svjatoslav.sixth.e3d.geometry.Point3D;
import eu.svjatoslav.sixth.e3d.gui.RenderingContext;
import eu.svjatoslav.sixth.e3d.gui.ViewSpaceTracker;
import eu.svjatoslav.sixth.e3d.gui.humaninput.MouseInteractionController;
import eu.svjatoslav.sixth.e3d.math.Transform;
import eu.svjatoslav.sixth.e3d.math.TransformStack;
import eu.svjatoslav.sixth.e3d.renderer.raster.Color;
import eu.svjatoslav.sixth.e3d.renderer.raster.RenderAggregator;
import eu.svjatoslav.sixth.e3d.renderer.raster.shapes.AbstractShape;
import eu.svjatoslav.sixth.e3d.renderer.raster.shapes.basic.line.Line;
import eu.svjatoslav.sixth.e3d.renderer.raster.shapes.basic.solidpolygon.SolidPolygon;
import eu.svjatoslav.sixth.e3d.renderer.raster.shapes.basic.texturedpolygon.TexturedPolygon;
import eu.svjatoslav.sixth.e3d.renderer.raster.slicer.Slicer;

import java.util.ArrayList;
import java.util.List;

/**
 * A composite shape that groups multiple sub-shapes into a single logical unit.
 *
 * <p>Use {@code 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.</p>
 *
 * <p><b>Usage example - creating a custom composite shape:</b></p>
 * <pre>{@code
 * // 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);
 * }</pre>
 *
 * <p><b>Level-of-detail slicing:</b></p>
 * <p>Textured polygons within the composite shape are automatically sliced into smaller
 * triangles based on distance from the viewer. This provides perspective-correct texture
 * mapping without requiring hardware support. The slicing factor adapts dynamically.</p>
 *
 * <p><b>Extending this class:</b></p>
 * <p>Override {@link #beforeTransformHook} to customize shape appearance or behavior
 * on each frame (e.g., animations, dynamic geometry updates).</p>
 *
 * @see SubShape wrapper for individual sub-shapes with group and visibility support
 * @see eu.svjatoslav.sixth.e3d.renderer.raster.shapes.AbstractShape the base shape class
 * @see eu.svjatoslav.sixth.e3d.renderer.raster.slicer.Slicer the level-of-detail polygon slicer
 */
public class AbstractCompositeShape extends AbstractShape {
    /**
     * The original sub-shapes added to this composite, each wrapped with group
     * identifier and visibility state. Shapes are stored in insertion order and
     * remain in this collection even when hidden.
     */
    private final List<SubShape> originalSubShapes = new ArrayList<>();

    /**
     * Tracks the distance and angle between the camera and this shape to compute
     * an appropriate slice factor for level-of-detail adjustments.
     */
    private final ViewSpaceTracker viewSpaceTracker;

    /**
     * The current slice factor used for tessellating textured polygons into smaller
     * triangles for perspective-correct rendering. Higher values produce more triangles
     * for distant objects; lower values for nearby objects. Updated dynamically based
     * on view-space analysis.
     */
    double currentSliceFactor = 5;

    /**
     * The processed list of sub-shapes ready for rendering. Contains non-textured
     * shapes directly, and sliced triangles for textured polygons. Regenerated when
     * {@link #slicingOutdated} is true.
     */
    private List<AbstractShape> renderedSubShapes = new ArrayList<>();

    /**
     * Flag indicating whether the rendered sub-shapes need to be regenerated.
     * Set to true when sub-shapes are added, removed, or when group visibility changes.
     */
    private boolean slicingOutdated = true;

    /**
     * The position and orientation transform for this composite shape.
     * Applied to all sub-shapes during the rendering transform pass.
     */
    private Transform transform;

    /**
     * Creates a composite shape at the world origin with no rotation.
     */
    public AbstractCompositeShape() {
        this(new Transform());
    }

    /**
     * Creates a composite shape at the specified location with no rotation.
     *
     * @param location the position in world space
     */
    public AbstractCompositeShape(final Point3D location) {
        this(new Transform(location));
    }

    /**
     * Creates a composite shape with the specified transform (position and orientation).
     *
     * @param transform the initial transform defining position and rotation
     */
    public AbstractCompositeShape(final Transform transform) {
        this.transform = transform;
        viewSpaceTracker = new ViewSpaceTracker();
    }

    /**
     * Adds a sub-shape to this composite shape without a group identifier.
     *
     * @param shape the shape to add
     */
    public void addShape(final AbstractShape shape) {
        addShape(shape, null);
    }

    /**
     * Adds a sub-shape to this composite shape with an optional group identifier.
     *
     * <p>Grouped shapes can be shown, hidden, or removed together using
     * {@link #showGroup}, {@link #hideGroup}, and {@link #removeGroup}.</p>
     *
     * @param shape   the shape to add
     * @param groupId the group identifier, or {@code null} for ungrouped shapes
     */
    public void addShape(final AbstractShape shape, final String groupId) {
        originalSubShapes.add(new SubShape(shape, groupId, true));
        slicingOutdated = true;
    }

    /**
     * This method should be overridden by anyone wanting to customize the shape
     * before it is rendered.
     *
     * @param transformPipe the current transform stack
     * @param context       the rendering context for the current frame
     */
    public void beforeTransformHook(final TransformStack transformPipe,
                                    final RenderingContext context) {
    }

    /**
     * Returns the world-space position of this composite shape.
     *
     * @return the translation component of this shape's transform
     */
    public Point3D getLocation() {
        return transform.getTranslation();
    }

    /**
     * Returns the list of all sub-shapes (including hidden ones).
     *
     * @return the internal list of sub-shapes
     */
    public List<SubShape> getOriginalSubShapes() {
        return originalSubShapes;
    }

    /**
     * Returns the view-space tracker that monitors the distance
     * and angle between the camera and this shape for level-of-detail adjustments.
     *
     * @return the view-space tracker for this shape
     */
    public ViewSpaceTracker getViewSpaceTracker() {
        return viewSpaceTracker;
    }

    /**
     * Hides all sub-shapes belonging to the specified group.
     * Hidden shapes are not rendered but remain in the collection.
     *
     * @param groupIdentifier the group to hide
     * @see #showGroup(String)
     * @see #removeGroup(String)
     */
    public void hideGroup(final String groupIdentifier) {
        for (final SubShape subShape : originalSubShapes) {
            if (subShape.matchesGroup(groupIdentifier)) {
                subShape.setVisible(false);
                slicingOutdated = true;
            }
        }
    }

    /**
     * Determines whether textured polygons need to be re-sliced based on slice factor change.
     * <p>
     * Re-slicing is needed if the slicing state is marked outdated, or if the ratio between
     * the larger and smaller slice factor exceeds 1.5x. This threshold prevents frequent
     * re-slicing for minor view changes while ensuring significant LOD changes trigger updates.
     *
     * @param proposedNewSliceFactor the slice factor computed from current view distance
     * @param currentSliceFactor     the slice factor currently in use
     * @return {@code true} if re-slicing should be performed
     */
    private boolean isReslicingNeeded(final double proposedNewSliceFactor, final double currentSliceFactor) {

        if (slicingOutdated)
            return true;

        // reslice if there is significant difference between proposed and current slice factor
        final double larger = Math.max(proposedNewSliceFactor, currentSliceFactor);
        final double smaller = Math.min(proposedNewSliceFactor, currentSliceFactor);

        return (larger / smaller) > 1.5d;
    }

    /**
     * Permanently removes all sub-shapes belonging to the specified group.
     *
     * @param groupIdentifier the group to remove
     * @see #hideGroup(String)
     */
    public void removeGroup(final String groupIdentifier) {
        final java.util.Iterator<SubShape> iterator = originalSubShapes
                .iterator();

        while (iterator.hasNext()) {
            final SubShape subShape = iterator.next();
            if (subShape.matchesGroup(groupIdentifier)) {
                iterator.remove();
                slicingOutdated = true;
            }
        }
    }

    /**
     * Returns all sub-shapes belonging to the specified group.
     *
     * @param groupIdentifier the group identifier to match
     * @return list of matching sub-shapes
     */
    public List<SubShape> getGroup(final String groupIdentifier) {
        final List<SubShape> result = new ArrayList<>();
        for (int i = 0; i < originalSubShapes.size(); i++) {
            final SubShape subShape = originalSubShapes.get(i);
            if (subShape.matchesGroup(groupIdentifier))
                result.add(subShape);
        }
        return result;
    }

    /**
     * Checks if re-slicing is needed and performs it if so.
     *
     * @param context the rendering context for logging
     */
    private void resliceIfNeeded(final RenderingContext context) {

        final double proposedSliceFactor = viewSpaceTracker.proposeSliceFactor();

        if (isReslicingNeeded(proposedSliceFactor, currentSliceFactor)) {
            currentSliceFactor = proposedSliceFactor;
            reslice(context);
        }
    }

    /**
     * Paint solid elements of this composite shape into given color.
     *
     * @param color the color to apply to all solid sub-shapes
     */
    public void setColor(final Color color) {
        for (final SubShape subShape : getOriginalSubShapes()) {
            final AbstractShape shape = subShape.getShape();

            if (shape instanceof SolidPolygon)
                ((SolidPolygon) shape).setColor(color);

            if (shape instanceof Line)
                ((Line) shape).color = color;
        }
    }

    /**
     * Assigns a group identifier to all sub-shapes that currently have no group.
     *
     * @param groupIdentifier the group to assign to ungrouped shapes
     */
    public void setGroupForUngrouped(final String groupIdentifier) {
        for (int i = 0; i < originalSubShapes.size(); i++) {
            final SubShape subShape = originalSubShapes.get(i);
            if (subShape.isUngrouped())
                subShape.setGroup(groupIdentifier);
        }
    }

    @Override
    public void setMouseInteractionController(
            final MouseInteractionController mouseInteractionController) {
        super.setMouseInteractionController(mouseInteractionController);

        for (final SubShape subShape : originalSubShapes)
            subShape.getShape().setMouseInteractionController(
                    mouseInteractionController);

        slicingOutdated = true;

    }

    /**
     * Replaces this shape's transform (position and orientation).
     *
     * @param transform the new transform to apply
     */
    public void setTransform(final Transform transform) {
        this.transform = transform;
    }

    /**
     * Enables or disables shading for all SolidPolygon sub-shapes.
     * When enabled, polygons use the global lighting manager from the rendering
     * context to calculate flat shading based on light sources.
     *
     * @param shadingEnabled {@code true} to enable shading, {@code false} to disable
     */
    public void setShadingEnabled(final boolean shadingEnabled) {
        for (final SubShape subShape : getOriginalSubShapes()) {
            final AbstractShape shape = subShape.getShape();
            if (shape instanceof SolidPolygon) {
                ((SolidPolygon) shape).setShadingEnabled(shadingEnabled);
            }

            // TODO: if shape is abstract composite, it seems that it would be good to enabled sharding recursively there too
        }
    }

    /**
     * Enables or disables backface culling for all SolidPolygon and TexturedPolygon sub-shapes.
     *
     * @param backfaceCulling {@code true} to enable backface culling, {@code false} to disable
     */
    public void setBackfaceCulling(final boolean backfaceCulling) {
        for (final SubShape subShape : getOriginalSubShapes()) {
            final AbstractShape shape = subShape.getShape();
            if (shape instanceof SolidPolygon) {
                ((SolidPolygon) shape).setBackfaceCulling(backfaceCulling);
            } else if (shape instanceof TexturedPolygon) {
                ((TexturedPolygon) shape).setBackfaceCulling(backfaceCulling);
            }
        }
    }

    /**
     * Makes all sub-shapes belonging to the specified group visible.
     *
     * @param groupIdentifier the group to show
     * @see #hideGroup(String)
     */
    public void showGroup(final String groupIdentifier) {
        for (int i = 0; i < originalSubShapes.size(); i++) {
            final SubShape subShape = originalSubShapes.get(i);
            if (subShape.matchesGroup(groupIdentifier)) {
                subShape.setVisible(true);
                slicingOutdated = true;
            }
        }
    }

    /**
     * Re-slices all textured polygons and rebuilds the rendered sub-shapes list.
     * Logs the operation to the debug log buffer if available.
     *
     * @param context the rendering context for logging, may be {@code null}
     */
    private void reslice(final RenderingContext context) {
        slicingOutdated = false;

        final List<AbstractShape> result = new ArrayList<>();

        final Slicer slicer = new Slicer(currentSliceFactor);
        int texturedPolygonCount = 0;
        int otherShapeCount = 0;

        for (int i = 0; i < originalSubShapes.size(); i++) {
            final SubShape subShape = originalSubShapes.get(i);
            if (subShape.isVisible()) {
                if (subShape.getShape() instanceof TexturedPolygon) {
                    slicer.slice((TexturedPolygon) subShape.getShape());
                    texturedPolygonCount++;
                } else {
                    result.add(subShape.getShape());
                    otherShapeCount++;
                }
            }
        }

        result.addAll(slicer.getResult());

        renderedSubShapes = result;

        // Log to developer tools console if available
        if (context != null && context.debugLogBuffer != null) {
            context.debugLogBuffer.log("reslice: " + getClass().getSimpleName()
                    + " sliceFactor=" + String.format("%.2f", currentSliceFactor)
                    + " texturedPolygons=" + texturedPolygonCount
                    + " otherShapes=" + otherShapeCount
                    + " resultingTexturedPolygons=" + slicer.getResult().size());
        }
    }

    @Override
    public void transform(final TransformStack transformPipe,
                          final RenderAggregator aggregator, final RenderingContext context) {

        // Add the current composite shape transform to the end of the transform
        // pipeline.
        transformPipe.addTransform(transform);

        viewSpaceTracker.analyze(transformPipe, context);

        beforeTransformHook(transformPipe, context);

        resliceIfNeeded(context);

        // transform rendered subshapes
        for (final AbstractShape shape : renderedSubShapes)
            shape.transform(transformPipe, aggregator, context);

        transformPipe.dropTransform();
    }

}