Author: paperwing
Date: 2012-02-05 20:31:59 -0800 (Sun, 05 Feb 2012)
New Revision: 28196
Modified:
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/BirdsEyeGraphicsHandler.java
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/CyActivator.java
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/Graphics.java
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/GraphicsHandler.java
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/MainGraphicsHandler.java
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/data/GraphicsData.java
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/rendering/ReadOnlyGraphicsProcedure.java
Log:
Added javadocs explaining the functionality of the following top-level and
generally important classes: Graphics, GraphicsHandler, MainGraphicsHandler,
BirdsEyeGraphicsHandler, GraphicsData, ReadOnlyRenderingProcedure
Modified:
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/BirdsEyeGraphicsHandler.java
===================================================================
---
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/BirdsEyeGraphicsHandler.java
2012-02-05 23:07:40 UTC (rev 28195)
+++
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/BirdsEyeGraphicsHandler.java
2012-02-06 04:31:59 UTC (rev 28196)
@@ -28,13 +28,30 @@
import org.cytoscape.view.model.CyNetworkView;
import org.cytoscape.view.model.VisualLexicon;
+/**
+ * An implementation of the {@link GraphicsHandler} interface used
+ * for bird's eye view rendering objects. This {@link GraphicsHandler}
+ * implementation thusly will not provide support for picking and
+ * advanced input handling, such as node and edge creation via the
+ * keyboard.
+ *
+ * @author Yue Dong
+ */
public class BirdsEyeGraphicsHandler implements GraphicsHandler {
-private List<ReadOnlyGraphicsProcedure> renderProcedures;
+ /**
+ * The list of {@link ReadOnlyGraphicsProcedure} objects, or
+ * rendering routines, that this {@link GraphicsHandler} employs.
+ * It may contain modified routines that specifically lower polygon
+ * detail for nodes or edges that are far away.
+ */
+ private List<ReadOnlyGraphicsProcedure> renderProcedures;
public BirdsEyeGraphicsHandler() {
+
+ // Populate the list of rendering routines employed by this
handler.
renderProcedures = new LinkedList<ReadOnlyGraphicsProcedure>();
-
+
renderProcedures.add(new ResetSceneProcedure());
renderProcedures.add(new PositionCameraProcedure());
renderProcedures.add(new RenderNodesProcedure());
@@ -69,21 +86,26 @@
}
+ /**
+ * Because this handler is designed for bird's eye view {@link Graphics}
+ * objects, it returns a dummy {@link ShapePickingProcessor} and does
not
+ * perform any shape picking data processing.
+ *
+ * @return A dummy {@link ShapePickingProcessor} object (no processing
is done).
+ */
@Override
public ShapePickingProcessor getShapePickingProcessor() {
+
+ // Return a ShapePickingProcessor that does not do any
processing
return new ShapePickingProcessor() {
@Override
public void initialize(GraphicsData graphicsData) {
- // TODO Auto-generated method stub
-
}
@Override
public void processPicking(MouseMonitor mouse,
KeyboardMonitor keys, GraphicsData
graphicsData) {
- // TODO Auto-generated method stub
-
}
};
@@ -107,12 +129,15 @@
@Override
public CytoscapeDataProcessor getCytoscapeDataProcessor() {
+
+ // Return a CytoscapeDataProcessor that does not do any
processing,
+ // because the bird's eye rendering object will not need to
access Cytoscape
+ // data.
return new CytoscapeDataProcessor() {
@Override
public void processCytoscapeData(GraphicsData
graphicsData) {
- // TODO Auto-generated method stub
-
+
}
};
}
Modified:
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/CyActivator.java
===================================================================
---
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/CyActivator.java
2012-02-05 23:07:40 UTC (rev 28195)
+++
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/CyActivator.java
2012-02-06 04:31:59 UTC (rev 28196)
@@ -13,6 +13,10 @@
import org.cytoscape.view.vizmap.VisualMappingManager;
import org.osgi.framework.BundleContext;
+/**
+ * CyActivator object used to import and export services from and to
Cytoscape, such
+ * as manager and factory objects.
+ */
public class CyActivator extends AbstractCyActivator {
public CyActivator() {
super();
Modified:
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/Graphics.java
===================================================================
---
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/Graphics.java
2012-02-05 23:07:40 UTC (rev 28195)
+++
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/Graphics.java
2012-02-06 04:31:59 UTC (rev 28196)
@@ -30,9 +30,19 @@
import org.cytoscape.view.model.CyNetworkView;
import org.cytoscape.view.model.VisualLexicon;
-/** The main class for the Wind rendering engines responsible for
- * creating graphics with the use of the JOGL (Java OpenGL) library
+/**
+ * This class represents a Wind rendering object, directly called
+ * by the display thread to update the rendered scene for every frame.
*
+ * Its behavior is governed by its {@link GraphicsHandler} object,
+ * which will determine if and how it handles the following:
+ * - keyboard and mouse input
+ * - calculation related to rendering
+ * - rendering of the network
+ * - communication with other {@link Graphics} objects, such as in the case
+ * of a bird's eye rendering object and a main window rendering object
communication
+ * with each other.
+ *
* @author Paperwing (Yue Dong)
*/
public class Graphics implements GLEventListener {
Modified:
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/GraphicsHandler.java
===================================================================
---
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/GraphicsHandler.java
2012-02-05 23:07:40 UTC (rev 28195)
+++
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/GraphicsHandler.java
2012-02-06 04:31:59 UTC (rev 28196)
@@ -2,6 +2,7 @@
import java.util.Map;
+import org.cytoscape.model.CyTable;
import org.cytoscape.paperwing.internal.coordinator.CoordinatorProcessor;
import org.cytoscape.paperwing.internal.coordinator.ViewingCoordinator;
import
org.cytoscape.paperwing.internal.cytoscape.processing.CytoscapeDataProcessor;
@@ -9,23 +10,104 @@
import org.cytoscape.paperwing.internal.input.InputProcessor;
import org.cytoscape.paperwing.internal.picking.ShapePickingProcessor;
import org.cytoscape.paperwing.internal.rendering.ReadOnlyGraphicsProcedure;
+import org.cytoscape.view.model.CyNetworkView;
-// The GraphicsHandler is read-only for given GraphicsData objects
+/**
+ * A handler object that is responsible for specifying how input, calculation,
and drawing are
+ * handled in a {@link Graphics} object. A {@link Graphics} object relies on
its GraphicsHandler
+ * to provide implementations for how certain responses are handled.
+ */
public interface GraphicsHandler {
+
+ /**
+ * Return a {@link ShapePickingProcessor} object that is responsible for
+ * performing shape picking and selection given the state of the
+ * network as well as the mouse. It will be given a {@link
GraphicsData} object
+ * to store its results.
+ *
+ * The {@link ShapePickingProcessor} is called first in the display
loop.
+ *
+ * @return A {@link ShapePickingProcessor} object that will perform
shape picking
+ * and store the results appropriately for later use.
+ */
+ public ShapePickingProcessor getShapePickingProcessor();
+ /**
+ * Return an {@link InputProcessor} that is responsible for responding
+ * to keyboard and mouse button input given the states of the keyboard
and
+ * mouse, as well as a {@link GraphicsData} object to store the
interpreted
+ * input data.
+ *
+ * The {@link InputProcessor} is called after the {@link
ShapePickingProcessor}.
+ *
+ * @return An {@link InputProcessor} that directs how input is handled.
+ */
public InputProcessor getInputProcessor();
- public ShapePickingProcessor getShapePickingProcessor();
+
+ /**
+ * Return an instance of a {@link ViewingCoordinator} that will be used
to allow
+ * communication between the bird's eye and the main rendering windows.
This communication
+ * is used to facilitate features such as being able to move the main
camera by clicking
+ * on the bird's eye view.
+ *
+ * @param graphicsData The {@link GraphicsData} object containing
relevant information about
+ * the current rendering object, such as the current {@link
CyNetworkView} being rendered
+ * @return An instance of a {@link ViewingCoordinator} used for
coordination between
+ * the main and bird's eye cameras.
+ */
public ViewingCoordinator getCoordinator(GraphicsData graphicsData);
+
+ /**
+ * Return an instance of a {@link CoordinatorProcessor} object, which
is responsible for
+ * interacting with the current {@link ViewingCoordinator} in order to
extract relevant data
+ * from another {@link Graphics} object. This could be information
about the position of
+ * the camera in the other {@link Graphics} object, for example.
+ *
+ * @return An instance of a {@link CoordinatorProcessor} object used to
interact with
+ * the {@link ViewingCoordinator}, which is also provided by this class.
+ */
public CoordinatorProcessor getCoordinatorProcessor();
+
+ /**
+ * Return an intance of a {@link CytoscapeDataProcessor}, which is
responsible for
+ * transferring data to and from Cytoscape's data objects, such as
{@link CyTable}.
+ * This could be used to update a value from a {@link CyTable}, or
retrieve a value
+ * from a {@link CyTable}.
+ *
+ * @return A {@link CytoscapeDataProcessor} object that is responsible
for modifying
+ * or retrieving data belonging to the rest of Cytoscape, such as data
belonging to
+ * a {@link CyTable} object.
+ */
public CytoscapeDataProcessor getCytoscapeDataProcessor();
- // Call procedures' init methods
+
+ /**
+ * This method should be called before the first frame of rendering. It
will initialize
+ * the rendering procedures (eg. setting up display lists) and allow
them to be
+ * executed for per-frame drawing, such as via the drawScene method.
+ *
+ * @param graphicsData The current {@link GraphicsData} object
containing information
+ * about the current state of rendering as well as the current state of
the network.
+ */
public void initializeGraphicsProcedures(GraphicsData graphicsData);
- // Draw the scene
+
+ /**
+ * This method is called to graphically render the current scene. It
should be
+ * called every frame if the state of the network during each frame is
desired
+ * to for visualization.
+ *
+ * @param graphicsData The current {@link GraphicsData} object
containing information
+ * about the current state of rendering as well as the current state of
the network.
+ */
public void drawScene(GraphicsData graphicsData);
- // Setup lighting
+ /**
+ * Sets up the lighting. Should be called before the first frame of
rendering.
+ *
+ * @param graphicsData @param graphicsData The current {@link
GraphicsData} object containing information
+ * about the current state of rendering as well as the current state of
the network.
+ */
public void setupLighting(GraphicsData graphicsData);
}
Modified:
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/MainGraphicsHandler.java
===================================================================
---
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/MainGraphicsHandler.java
2012-02-05 23:07:40 UTC (rev 28195)
+++
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/MainGraphicsHandler.java
2012-02-06 04:31:59 UTC (rev 28196)
@@ -25,20 +25,34 @@
import org.cytoscape.paperwing.internal.rendering.text.StringRenderer;
import org.cytoscape.view.model.CyNetworkView;
+/**
+ * An implementation for the {@link GraphicsHandler} interface to be used
+ * for main rendering windows. That is, this handler fully supports keyboard
+ * and mouse input, as well as selection and picking.
+ *
+ * @author Yue Dong
+ */
public class MainGraphicsHandler implements GraphicsHandler {
+ /**
+ * The list of {@link ReadOnlyGraphicsProcedure} objects, or
+ * rendering routines, that this {@link GraphicsHandler} uses.
+ */
private List<ReadOnlyGraphicsProcedure> renderProcedures;
+
public MainGraphicsHandler() {
renderProcedures = new LinkedList<ReadOnlyGraphicsProcedure>();
-
+
+ // Populate the list of rendering routines that this
GraphicsHandler
+ // uses.
+ // The routines will be executed in the order that they are
added.
renderProcedures.add(new ResetSceneProcedure());
renderProcedures.add(new PositionCameraProcedure());
renderProcedures.add(new RenderNodesProcedure());
renderProcedures.add(new RenderArcEdgesProcedure());
renderProcedures.add(new RenderSelectionBoxProcedure());
-// renderProcedures.add(new RenderNodeLabelsProcedure());
}
@Override
Modified:
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/data/GraphicsData.java
===================================================================
---
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/data/GraphicsData.java
2012-02-05 23:07:40 UTC (rev 28195)
+++
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/data/GraphicsData.java
2012-02-06 04:31:59 UTC (rev 28196)
@@ -7,22 +7,34 @@
import javax.media.opengl.glu.GLU;
import org.cytoscape.paperwing.internal.Graphics;
+import org.cytoscape.paperwing.internal.coordinator.ViewingCoordinator;
import org.cytoscape.paperwing.internal.geometric.Vector3;
import org.cytoscape.paperwing.internal.tools.SimpleCamera;
import org.cytoscape.view.model.CyNetworkView;
import org.cytoscape.view.model.VisualLexicon;
+/**
+ * This class represents a data object in which data relevant to the renderer,
+ * such as the position of the camera, the number of frames elapsed, the
coordinates
+ * of the current drag selection box, is stored. Information about the current
state
+ * of the network is also stored in this object.
+ *
+ * This class is mostly responsible for storing the renderer's data, and
allowing
+ * access to the data through getter and setter objects.
+ *
+ * @author Paperwing (Yue Dong)
+ */
public class GraphicsData {
/** The network view to be rendered */
private CyNetworkView networkView;
/**
- * This value controls distance scaling when converting from node
- * coordinates to drawing coordinates
+ * This value controls distance scaling when converting from Cytoscape
+ * coordinates (such as from Ding) to the renderer's 3D coordinates
*/
private float distanceScale = 178.0f;
-
+
private float verticalFov = 45.0f;
/** The camera to use for transformation of 3D scene */
@@ -46,8 +58,27 @@
/** A boolean to disable real-time shape picking to improve framerate */
private boolean disableHovering;
+ /**
+ * A {@link GraphicsSelectionData} object which is responsible for
+ * storing all data related to selection of objects in the network, such
+ * as indices of currently selected nodes, or the coordinates of the
current
+ * selection box.
+ * */
private GraphicsSelectionData selectionData;
+
+ /**
+ * A {@link CoordinatorData} object responsible for storing data
related to
+ * the relevant {@link ViewingCoordinator}, ie. it stores the data
related
+ * to coordination with another {@link Graphics} object, such as in the
+ * relationship between bird's eye and main window rendering objects.
+ */
private CoordinatorData coordinatorData;
+
+ /**
+ * A {@link PickingData} object responsible for storing data related to
the
+ * current picking state of the renderer, such as the index and type
+ * of the object that was found under the current mouse cursor.
+ */
private PickingData pickingData;
private GL2 glContext;
Modified:
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/rendering/ReadOnlyGraphicsProcedure.java
===================================================================
---
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/rendering/ReadOnlyGraphicsProcedure.java
2012-02-05 23:07:40 UTC (rev 28195)
+++
csplugins/trunk/toronto/yuedong/paperwing-impl/src/main/java/org/cytoscape/paperwing/internal/rendering/ReadOnlyGraphicsProcedure.java
2012-02-06 04:31:59 UTC (rev 28196)
@@ -7,8 +7,34 @@
import org.cytoscape.paperwing.internal.Graphics;
import org.cytoscape.paperwing.internal.data.GraphicsData;
+/**
+ * This class represents a rendering procedure. Rendering procedures
+ * are meant to only read provided data and not write any data. They
+ * are usually freely allowed to read the given data to carry out its
+ * rendering task (such as drawing all the nodes of a network, or
+ * the drag selection box).
+ *
+ * @author Yue Dong (Paperwing)
+ */
public interface ReadOnlyGraphicsProcedure {
+
+ /**
+ * Initialize the graphics procedure, if any intialization is needed.
+ *
+ * @param graphicsData The {@link GraphicsData} object containing
+ * relevant information about the current state of rendering. This class
+ * is permitted generally only to read from this data object and not do
+ * any writing.
+ */
public void initialize(GraphicsData graphicsData);
+ /**
+ * Execute the graphics procedure.
+ *
+ * @param graphicsData The {@link GraphicsData} object containing
information
+ * about the current state of rendering. The {@link
ReadOnlyGraphicsProcedure}
+ * is allowed to freely read from this data object to carry out its
task, but it
+ * is generally not permitted to write to it.
+ */
public void execute(GraphicsData graphicsData);
}
--
You received this message because you are subscribed to the Google Groups
"cytoscape-cvs" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/cytoscape-cvs?hl=en.
