[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.lighting.LightingManager;
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 {
    private final List<SubShape> originalSubShapes = new ArrayList<>();
    private final ViewSpaceTracker viewSpaceTracker;
    double currentSliceFactor = 5;
    private List<AbstractShape> renderedSubShapes = new ArrayList<>();
    private boolean slicingOutdated = true;
    private Transform transform;
    private LightingManager lightingManager;

    /**
     * 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) {
        final SubShape subShape = new SubShape(shape);
        subShape.setGroup(groupId);
        subShape.setVisible(true);
        originalSubShapes.add(subShape);
        slicingOutdated = true;
    }

    /**
     * This method should be overridden by anyone wanting to customize 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 (int i = 0; i < originalSubShapes.size(); i++) {
            final SubShape subShape = originalSubShapes.get(i);
            if (subShape.matchesGroup(groupIdentifier)) {
                subShape.setVisible(false);
                slicingOutdated = true;
            }
        }
    }

    private boolean isReslicingNeeded(double proposedNewSliceFactor, double currentSliceFactor) {

        if (slicingOutdated)
            return true;

        // reslice if there is significant difference between proposed and current slice factor
        if (proposedNewSliceFactor > currentSliceFactor) {
            final double tmp = proposedNewSliceFactor;
            proposedNewSliceFactor = currentSliceFactor;
            currentSliceFactor = tmp;
        }

        return (currentSliceFactor / proposedNewSliceFactor) > 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;
    }

    private void resliceIfNeeded() {

        final double proposedSliceFactor = viewSpaceTracker.proposeSliceFactor();

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

    /**
     * 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;
    }

    /**
     * Sets the lighting manager for this composite shape and enables shading on all SolidPolygon sub-shapes.
     *
     * @param lightingManager the lighting manager to use for shading calculations
     */
    public void setLightingManager(final LightingManager lightingManager) {
        this.lightingManager = lightingManager;
        applyShadingToPolygons();
    }

    /**
     * Enables or disables shading for all SolidPolygon sub-shapes.
     *
     * @param shadingEnabled true to enable shading, 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, lightingManager);
            }
        }
    }

    private void applyShadingToPolygons() {
        if (lightingManager == null)
            return;

        for (final SubShape subShape : getOriginalSubShapes()) {
            final AbstractShape shape = subShape.getShape();
            if (shape instanceof SolidPolygon) {
                ((SolidPolygon) shape).setShadingEnabled(true, lightingManager);
            }
        }
    }

    /**
     * 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;
            }
        }
    }

    private void reslice() {
        slicingOutdated = false;

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

        final Slicer slicer = new Slicer(currentSliceFactor);
        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());
                else
                    result.add(subShape.getShape());
            }
        }

        result.addAll(slicer.getResult());

        renderedSubShapes = result;
    }

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

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

        viewSpaceTracker.analyze(transformPipe, context);

        beforeTransformHook(transformPipe, context);

        // hack, to get somewhat perspective correct textures
        resliceIfNeeded();

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

        transformPipe.dropTransform();
    }

}