From ef4bbe7548ec78cf49e2d430f480903ee77a4fc6 Mon Sep 17 00:00:00 2001 From: Quentin Legot Date: Thu, 15 Apr 2021 18:40:33 +0200 Subject: [PATCH] Add comments to methods, classes and package, add overview.html and move Type.java --- build.xml | 4 ++-- overview.html | 12 ++++++++++ src/lsystem/engine/Element.java | 2 ++ src/lsystem/engine/Parser.java | 1 - src/lsystem/{ => engine}/Type.java | 2 +- src/lsystem/engine/package-info.java | 4 ++++ src/lsystem/screen/gl3d/AbstractCanvas.java | 12 ++++++---- src/lsystem/screen/gl3d/AbstractListener.java | 13 +++++++++++ src/lsystem/screen/gl3d/DrawHelper.java | 11 +++++++++- src/lsystem/screen/gl3d/GLEventListener.java | 22 +++++++++++++++++++ .../screen/gl3d/GLKeyboardListener.java | 3 +++ src/lsystem/screen/gl3d/GLMouseListener.java | 8 +++++++ src/lsystem/screen/gl3d/package-info.java | 4 ++++ src/lsystem/screen/main/Tab.java | 22 +++++++++---------- src/lsystem/screen/main/package-info.java | 4 ++++ 15 files changed, 104 insertions(+), 20 deletions(-) create mode 100644 overview.html rename src/lsystem/{ => engine}/Type.java (61%) create mode 100644 src/lsystem/engine/package-info.java create mode 100644 src/lsystem/screen/gl3d/package-info.java create mode 100644 src/lsystem/screen/main/package-info.java diff --git a/build.xml b/build.xml index b225359..ed0e27f 100644 --- a/build.xml +++ b/build.xml @@ -33,12 +33,12 @@ - + - + diff --git a/overview.html b/overview.html new file mode 100644 index 0000000..f797adf --- /dev/null +++ b/overview.html @@ -0,0 +1,12 @@ + +

L-System

+ +

+ L-System javadoc +

+ +

If you searching for 3d windows, go in the {@link lsystem.screen.gl3d} package

+

For all in-depth (backend) methods, go in {@link lsystem.engine} package

+

To view all classes, click here

+ + \ No newline at end of file diff --git a/src/lsystem/engine/Element.java b/src/lsystem/engine/Element.java index ba2ac71..5282174 100644 --- a/src/lsystem/engine/Element.java +++ b/src/lsystem/engine/Element.java @@ -16,10 +16,12 @@ public class Element { */ public final ElementProperties property; public final Element parent; + /** * Rotation applied to this element, 3-dim tab which represent yaw, pitch and roll rotation */ public final float[] rotation; + /** * Branches of the tree */ diff --git a/src/lsystem/engine/Parser.java b/src/lsystem/engine/Parser.java index 7b9e4fe..2a92464 100644 --- a/src/lsystem/engine/Parser.java +++ b/src/lsystem/engine/Parser.java @@ -1,6 +1,5 @@ package lsystem.engine; -import lsystem.Type; import lsystem.screen.Constants; import lsystem.utils.Pair; diff --git a/src/lsystem/Type.java b/src/lsystem/engine/Type.java similarity index 61% rename from src/lsystem/Type.java rename to src/lsystem/engine/Type.java index 43801af..a60e431 100644 --- a/src/lsystem/Type.java +++ b/src/lsystem/engine/Type.java @@ -1,4 +1,4 @@ -package lsystem; +package lsystem.engine; public enum Type { diff --git a/src/lsystem/engine/package-info.java b/src/lsystem/engine/package-info.java new file mode 100644 index 0000000..de1a2d2 --- /dev/null +++ b/src/lsystem/engine/package-info.java @@ -0,0 +1,4 @@ +/** + * all backend classes: {@link lsystem.engine.Parser}, {@link lsystem.engine.Rewrite Rewriter} and {@link lsystem.engine.Element L-System} + */ +package lsystem.engine; \ No newline at end of file diff --git a/src/lsystem/screen/gl3d/AbstractCanvas.java b/src/lsystem/screen/gl3d/AbstractCanvas.java index 42db1ae..71efea7 100644 --- a/src/lsystem/screen/gl3d/AbstractCanvas.java +++ b/src/lsystem/screen/gl3d/AbstractCanvas.java @@ -58,8 +58,12 @@ public abstract class AbstractCanvas { lSystem = null; parsedState = State.FINISH_OR_NULL; // after setting lSystem to null, the object can be large (up to 4gb during our tests) and it's stored - // long time in memory - // the partial gc only clear the object itself and absolutely not all of its children from memory + // long time in memory. + // the partial gc only clear the object itself and absolutely not all of its children from memory. + // Doing a full garbage collector will pause the program (stop the world) depending of your computer performance + // but we use -XX:+ParallelRefProcEnabled launch argument which should decrease time used by gc and use + // -XX:+UseG1GC to force jre 1.8 to use G1GC (G1GC is default on jre 11+), if you have jre 15+ you should use + // ZGC which is very quick compared to G1GC and have a lower CPU usage System.gc(); } }); @@ -71,8 +75,8 @@ public abstract class AbstractCanvas { protected abstract void addEventsListeners(); /** - * if {@code bl} is true, we start the animator and then display the window - * @param bl + * + * @param bl if true, we start the animator and then display the window, if false stop the animator and hide the window */ public void setVisible(boolean bl) { if(bl) diff --git a/src/lsystem/screen/gl3d/AbstractListener.java b/src/lsystem/screen/gl3d/AbstractListener.java index d665e55..ed2add2 100644 --- a/src/lsystem/screen/gl3d/AbstractListener.java +++ b/src/lsystem/screen/gl3d/AbstractListener.java @@ -7,6 +7,9 @@ import com.jogamp.opengl.glu.GLU; import com.jogamp.opengl.util.gl2.GLUT; import lsystem.engine.Element; +/** + * use to setup viewport + */ public abstract class AbstractListener implements GLEventListener { protected final AbstractCanvas canvas; @@ -21,6 +24,10 @@ public abstract class AbstractListener implements GLEventListener { this.glut = canvas.glut; } + /** + * init and enable openGL functionalities + * @param glAutoDrawable openGL drawable surface + */ @Override public void init(GLAutoDrawable glAutoDrawable) { GL2 gl = glAutoDrawable.getGL().getGL2(); @@ -44,6 +51,12 @@ public abstract class AbstractListener implements GLEventListener { public void dispose(GLAutoDrawable glAutoDrawable) { } + /** + * call when window is resized or moved + * @param glAutoDrawable openGL drawable surface + * @param width window width + * @param height window height + */ @Override public void reshape(GLAutoDrawable glAutoDrawable, int x, int y, int width, int height) { GL2 gl = glAutoDrawable.getGL().getGL2(); diff --git a/src/lsystem/screen/gl3d/DrawHelper.java b/src/lsystem/screen/gl3d/DrawHelper.java index 0053966..9296a1d 100644 --- a/src/lsystem/screen/gl3d/DrawHelper.java +++ b/src/lsystem/screen/gl3d/DrawHelper.java @@ -5,6 +5,9 @@ import com.jogamp.opengl.util.gl2.GLUT; import lsystem.engine.Element; import lsystem.engine.ElementProperties; +/** + * static function use when to draw some figures + */ public class DrawHelper { public static void placeCamera(GL2 gl, AbstractCanvas canvas) { @@ -44,6 +47,13 @@ public class DrawHelper { glut.glutBitmapCharacter(GLUT.BITMAP_HELVETICA_18, 'Z'); // draw the z axis } + /** + * draw the L-System, move the camera and then use recursive call to draw branches of {@code element} + * @param listener use to move the camera depending of the size if the L-System + * @param gl use to move cursor + * @param glut use to draw pre implemented function like {@link GLUT#glutSolidCylinder(double, double, int, int)} + * @param element working branch of the {@link Element LSystem} + */ public static void drawLSystem(AbstractListener listener, GL2 gl, GLUT glut, Element element) { gl.glPushMatrix(); gl.glRotatef(element.rotation[0] * 360, 1f, 0f, 0f); @@ -66,7 +76,6 @@ public class DrawHelper { gl.glPopMatrix(); } - @SuppressWarnings("unused") public static void drawDebugInformation(GL2 gl, GLUT glut, AbstractCanvas canvas) { gl.glRasterPos3f(canvas.camera[0], canvas.camera[1], canvas.camera[2] - 1); diff --git a/src/lsystem/screen/gl3d/GLEventListener.java b/src/lsystem/screen/gl3d/GLEventListener.java index 5d14b7e..90a40be 100644 --- a/src/lsystem/screen/gl3d/GLEventListener.java +++ b/src/lsystem/screen/gl3d/GLEventListener.java @@ -5,6 +5,10 @@ import com.jogamp.opengl.GLAutoDrawable; import lsystem.engine.Element; import lsystem.screen.Constants; +/** + * use to draw the 3d scene + * @see AbstractListener + */ public class GLEventListener extends AbstractListener { private final float[] light_0_position = {1000f, 1000f, 1000f, 1f}; @@ -15,6 +19,10 @@ public class GLEventListener extends AbstractListener { } + /** + * init and enable openGL functionalities + * @param glAutoDrawable openGL drawable surface + */ @Override public void init(GLAutoDrawable glAutoDrawable) { GL2 gl = glAutoDrawable.getGL().getGL2(); @@ -39,6 +47,10 @@ public class GLEventListener extends AbstractListener { firstGen = true; } + /** + * call at each frame (without pause if fps are lower than you screen refresh rate) + * @param glAutoDrawable openGL drawable surface + */ @Override public void display(GLAutoDrawable glAutoDrawable) { for (int i = 0; i < canvas.camera.length; i++) { @@ -62,11 +74,21 @@ public class GLEventListener extends AbstractListener { gl.glFlush(); fps++; } + + @Override public void drawLSystem(GL2 gl, Element element) { DrawHelper.drawLSystem(this, gl, glut, element); } + + /** + * call when window is resized or moved + * @see AbstractListener#reshape(GLAutoDrawable, int, int, int, int) + * @param glAutoDrawable openGL drawable surface + * @param width window width + * @param height window height + */ @Override public void reshape(GLAutoDrawable glAutoDrawable, int x, int y, int width, int height) { super.reshape(glAutoDrawable, x, y, width, height); diff --git a/src/lsystem/screen/gl3d/GLKeyboardListener.java b/src/lsystem/screen/gl3d/GLKeyboardListener.java index 4852213..2aa4c8c 100644 --- a/src/lsystem/screen/gl3d/GLKeyboardListener.java +++ b/src/lsystem/screen/gl3d/GLKeyboardListener.java @@ -13,6 +13,9 @@ public class GLKeyboardListener implements KeyListener { this.canvas = swingGLCanvas; } + /** + * use to move camera depending of key used + */ @Override public void keyTyped(KeyEvent e) { diff --git a/src/lsystem/screen/gl3d/GLMouseListener.java b/src/lsystem/screen/gl3d/GLMouseListener.java index 7451848..063c9b9 100644 --- a/src/lsystem/screen/gl3d/GLMouseListener.java +++ b/src/lsystem/screen/gl3d/GLMouseListener.java @@ -48,6 +48,11 @@ public class GLMouseListener implements MouseListener, MouseMotionListener, Mous public void mouseExited(MouseEvent e) { } + /** + * use to move camera rotation without move + * @see #mouseDragged(MouseEvent) + * @see #mouseReleased(MouseEvent) + */ @Override public void mouseDragged(MouseEvent e) { if(origine != null) { @@ -65,6 +70,9 @@ public class GLMouseListener implements MouseListener, MouseMotionListener, Mous public void mouseMoved(MouseEvent e) { } + /** + * use to move forward or backward + */ @Override public void mouseWheelMoved(MouseWheelEvent e) { canvas.camera[2] += Math.cos(Math.toRadians(canvas.camera[4]))*MULTIPLIER* e.getWheelRotation()*Math.cos(Math.toRadians(Math.abs(360-canvas.camera[3]))); diff --git a/src/lsystem/screen/gl3d/package-info.java b/src/lsystem/screen/gl3d/package-info.java new file mode 100644 index 0000000..573a6d5 --- /dev/null +++ b/src/lsystem/screen/gl3d/package-info.java @@ -0,0 +1,4 @@ +/** + * 3d window package. contains all classes related + */ +package lsystem.screen.gl3d; \ No newline at end of file diff --git a/src/lsystem/screen/main/Tab.java b/src/lsystem/screen/main/Tab.java index 3ad3546..b81e99a 100644 --- a/src/lsystem/screen/main/Tab.java +++ b/src/lsystem/screen/main/Tab.java @@ -15,8 +15,8 @@ public class Tab extends JPanel{ /** * A method which create a new instance of the class JPanel ready to be added to the MainFrame's tabs variable (JTabbedPane). - * @param nbTabs -> the number of this tab, useful for the listener. - * @param frame -> the MainFrame instance that is useful to access all the components. + * @param nbTabs the number of this tab, useful for the listener. + * @param frame the MainFrame instance that is useful to access all the components. */ public Tab(int nbTabs,MainFrame frame) { @@ -80,7 +80,7 @@ public class Tab extends JPanel{ /** * Create and return a newly created TextArea component. - * @param texte -> the text that will be added in the returned component. + * @param texte the text that will be added in the returned component. * @return A JTextArea component. */ public JTextArea textArea(String texte){ @@ -94,9 +94,9 @@ public class Tab extends JPanel{ /** * Fuse two components into a JPanel component organized with given GridBagConstraints. - * @param a -> the first component to add in the JPanel. - * @param b -> the second component to add in the JPanel. - * @param gc -> the GridBagConstraints given to organise the two fused components. + * @param a the first component to add in the JPanel. + * @param b the second component to add in the JPanel. + * @param gc the GridBagConstraints given to organise the two fused components. * @return A JPanel component. */ public JPanel subPanel(Component a, Component b,GridBagConstraints gc){ @@ -116,7 +116,7 @@ public class Tab extends JPanel{ /** * An accessor to the axiomList and the rulesList - * @param i -> a byte which indicates which component to return (axiomList or rulesList). + * @param i a byte which indicates which component to return (axiomList or rulesList). * @return A JTextArea component. */ public JTextArea getTextArea(byte i){ @@ -125,7 +125,7 @@ public class Tab extends JPanel{ /** * An accessor to the axiomField and the rulesField. - * @param i -> a byte which indicates which component to return (axiomField or rulesField). + * @param i a byte which indicates which component to return (axiomField or rulesField). * @return A JTextField component. */ public JTextField getTextField(byte i){ @@ -134,9 +134,9 @@ public class Tab extends JPanel{ /** * Checks if the maximal axioms number has been reach, if not, add the given String into the axiomList or into the rulesList. - * @param stringToAdd -> the String to add into the JTextArea. - * @param list -> the JTextArea where to add the String (axiomList or rulesList). - * @param nb -> the number of Axioms that are already created (maximum 1). + * @param stringToAdd the String to add into the JTextArea. + * @param list the JTextArea where to add the String (axiomList or rulesList). + * @param nb the number of Axioms that are already created (maximum 1). */ public void changeList(String stringToAdd, JTextArea list, int nb) { if(nb > 0) diff --git a/src/lsystem/screen/main/package-info.java b/src/lsystem/screen/main/package-info.java new file mode 100644 index 0000000..a5a13d2 --- /dev/null +++ b/src/lsystem/screen/main/package-info.java @@ -0,0 +1,4 @@ +/** + * Interface window. contains all classes related to menu and end-user interactions + */ +package lsystem.screen.main; \ No newline at end of file