JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
Container.java
Go to the documentation of this file.
1/**
2 * Copyright 2023-2024 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28package com.jogamp.graph.ui;
29
30import java.util.Collection;
31import java.util.List;
32
33import com.jogamp.math.Matrix4f;
34import com.jogamp.math.geom.AABBox;
35import com.jogamp.math.util.PMVMatrix4f;
36import com.jogamp.opengl.GL2ES2;
37import com.jogamp.graph.curve.opengl.RegionRenderer;
38
39/**
40 * Container interface of UI {@link Shape}s
41 * @see Scene
42 * @see Shape
43 */
44public interface Container {
45
46 /** Returns number of {@link Shape}s, see {@link #getShapes()}. */
48
49 /** Returns {@link #addShape(Shape) added} {@link Shape}s. */
50 List<Shape> getShapes();
51
52 /**
53 * Returns {@link #addShape(Shape) added shapes} which are rendered and sorted by z-axis in ascending order toward z-near.
54 * <p>
55 * The rendered shapes are {@link Shape#isVisible() visible} and not deemed outside of this container due to {@link #isCullingEnabled() culling}.
56 * </p>
57 * <p>
58 * Only rendered shapes are considered for picking/activation.
59 * </p>
60 * <p>
61 * The returned list is data-race free, i.e. won't be mutated by the rendering thread
62 * as it gets completely replace at each rendering loop using a local volatile reference.<br/>
63 * Only when disposing the container, the list gets cleared, hence {@Link List#size()} shall be used in the loop.
64 * </p>
65 * @see #addShape(Shape)
66 * @see #isCullingEnabled()
67 * @see Shape#isVisible()
68 * @see #isOutside(PMVMatrix4f, Shape)
69 */
70 List<Shape> getRenderedShapes();
71
72 /** Adds a {@link Shape}. */
73 void addShape(Shape s);
74
75 /**
76 * Removes given shape, w/o {@link Shape#destroy(GL2ES2, RegionRenderer)}.
77 * @return the removed shape or null if not contained
78 */
80
81 /** Removes all given shapes, w/o {@link Shape#destroy(GL2ES2, RegionRenderer)}. */
82 void removeShapes(Collection<? extends Shape> shapes);
83
84 /**
85 * Removes given shape with {@link Shape#destroy(GL2ES2, RegionRenderer)}, if contained.
86 * @param gl GL2ES2 context
87 * @param renderer
88 * @param s the shape to be removed
89 * @return true if given Shape is removed and destroyed
90 */
91 boolean removeShape(final GL2ES2 gl, final RegionRenderer renderer, final Shape s);
92
93 void addShapes(Collection<? extends Shape> shapes);
94
95 /** Removes all given shapes with {@link Shape#destroy(GL2ES2, RegionRenderer)}. */
96 void removeShapes(final GL2ES2 gl, final RegionRenderer renderer, final Collection<? extends Shape> shapes);
97
98 /** Removes all contained shapes with {@link Shape#destroy(GL2ES2, RegionRenderer)}. */
99 void removeAllShapes(final GL2ES2 gl, final RegionRenderer renderer);
100
101 boolean contains(Shape s);
102
103 Shape getShapeByIdx(final int id);
104 Shape getShapeByID(final int id);
105 Shape getShapeByName(final String name);
106
107 /** Returns {@link AABBox} dimension of given {@link Shape} from this container's perspective, i.e. world-bounds if performing from the {@link Scene}. */
109
110 /** Enable or disable {@link PMVMatrix4f#getFrustum() Project-Modelview (PMv) frustum} culling per {@link Shape} for this container. Default is disabled. */
111 void setPMvCullingEnabled(final boolean v);
112
113 /** Return whether {@link #setPMvCullingEnabled(boolean) Project-Modelview (PMv) frustum culling} is enabled for this container. */
115
116 /**
117 * Return whether {@link #setPMvCullingEnabled(boolean) Project-Modelview (PMv) frustum culling}
118 * or {@link Group#setClipMvFrustum(com.jogamp.math.geom.Frustum) Group's Modelview (Mv) frustum clipping}
119 * is enabled for this container. Default is disabled.
120 */
122
123 /**
124 * Returns whether the given {@link Shape} is completely outside of this container.
125 * <p>
126 * Note: If method returns false, the box may only be partially inside, i.e. intersects with this container
127 * </p>
128 * @param pmv current {@link PMVMatrix4f} of this container
129 * @param shape the {@link Shape} to test
130 * @see #isOutside2(Matrix4f, Shape, PMVMatrix4f)
131 * @see Shape#isOutside()
132 */
133 public boolean isOutside(final PMVMatrix4f pmv, final Shape shape);
134
135 /**
136 * Returns whether the given {@link Shape} is completely outside of this container.
137 * <p>
138 * Note: If method returns false, the box may only be partially inside, i.e. intersects with this container
139 * </p>
140 * @param mvCont copy of the model-view {@link Matrix4f) of this container
141 * @param shape the {@link Shape} to test
142 * @param pmvShape current {@link PMVMatrix4f} of the shape to test
143 * @see #isOutside(PMVMatrix4f, Shape)
144 * @see Shape#isOutside()
145 */
146 public boolean isOutside2(final Matrix4f mvCont, final Shape shape, final PMVMatrix4f pmvShape);
147}
Generic Shape, potentially using a Graph via GraphShape or other means of representing content.
Definition: Shape.java:87
Basic 4x4 float matrix implementation using fields for intensive use-cases (host operations).
Definition: Matrix4f.java:89
Axis Aligned Bounding Box.
Definition: AABBox.java:54
PMVMatrix4f implements the basic computer graphics Matrix4f pack using projection (P),...
Container interface of UI Shapes.
Definition: Container.java:44
void setPMvCullingEnabled(final boolean v)
Enable or disable Project-Modelview (PMv) frustum culling per Shape for this container.
void removeAllShapes(final GL2ES2 gl, final RegionRenderer renderer)
Removes all contained shapes with Shape#destroy(GL2ES2, RegionRenderer).
int getShapeCount()
Returns number of Shapes, see getShapes().
Shape removeShape(final Shape s)
Removes given shape, w/o Shape#destroy(GL2ES2, RegionRenderer).
boolean isOutside2(final Matrix4f mvCont, final Shape shape, final PMVMatrix4f pmvShape)
Returns whether the given Shape is completely outside of this container.
boolean removeShape(final GL2ES2 gl, final RegionRenderer renderer, final Shape s)
Removes given shape with Shape#destroy(GL2ES2, RegionRenderer), if contained.
boolean isOutside(final PMVMatrix4f pmv, final Shape shape)
Returns whether the given Shape is completely outside of this container.
void removeShapes(Collection<? extends Shape > shapes)
Removes all given shapes, w/o Shape#destroy(GL2ES2, RegionRenderer).
List< Shape > getRenderedShapes()
Returns added shapes which are rendered and sorted by z-axis in ascending order toward z-near.
boolean isCullingEnabled()
Return whether Project-Modelview (PMv) frustum culling or Group's Modelview (Mv) frustum clipping is ...
List< Shape > getShapes()
Returns added Shapes.
Shape getShapeByName(final String name)
void removeShapes(final GL2ES2 gl, final RegionRenderer renderer, final Collection<? extends Shape > shapes)
Removes all given shapes with Shape#destroy(GL2ES2, RegionRenderer).
Shape getShapeByID(final int id)
AABBox getBounds(final PMVMatrix4f pmv, Shape shape)
Returns AABBox dimension of given Shape from this container's perspective, i.e.
void addShape(Shape s)
Adds a Shape.
Shape getShapeByIdx(final int id)
boolean isPMvCullingEnabled()
Return whether Project-Modelview (PMv) frustum culling is enabled for this container.
void addShapes(Collection<? extends Shape > shapes)