org.proteinshader.graphics.adapter
Class StructureToGraphics

java.lang.Object
  org.proteinshader.graphics.adapter.StructureToGraphics

public class StructureToGraphics
extends Object

Knows how to get numbers (such as zyz-coordinates and colors) from a Drawable object (Atom, Bond, or Segment) and plug them into the right graphics class for rendering a Shape (Sphere, Cylinder, or Segment).

When the program first starts up, OpenGL display lists for spheres and cylinders will be cached, so actually rendering of spheres and cylinders will be sped up by calling on OpenGL display lists rather than rendering on-the-fly. Ribbon and tube segments will be cached as OpenGL display lists whenever ribbons or tubes is selected from the Cartoon submenu of the Style menu above the canvas, so normally all rendering of ribbon and tube segments will be sped up by calling on cached geometry.

On a fairly new (less than a year old) Macintosh 2.16 GHz Intel Core 2 Duo with an ATI Radeon X1600 graphics card, using OpenGL display lists results in about 10 times faster rendering for tubes, 9 times faster rendering for ribbons, and 7 times faster rendering for spheres. However, the exact difference in frames per second during an animation will probably vary depending on the machine and graphics card.

To allows testing of the effects of caching geometry in the form of OpenGL display lists, the StructureToGraphics class has a boolean instance variable named renderOnTheFly that can be used to shut off the use of OpenGL display lists for rendering spheres, ribbon segments, and tube segments, so that calls to Java drawing routines will be made every time a frame is rendered. The renderOnTheFly variable is normally set to false, but can be set to true by giving the command line argument "-DrenderOnTheFly=true" when staring the program. If Ant (a Java build tool) is installed, the program can be started by typing "ant run.slow" on the command line instead of "ant run".

Field Summary

static boolean

AUTO_TILING Automatic tiling (level of detail) for spheres and cylinders is set to true by default.

Constructor Summary

StructureToGraphics()
Constructs a StructureToGraphics object.

Method Summary

void	blendObjectEdges(boolean b) Turns on or off the ability of the halftoning shaders to soften aliasing (jagged edges) by rendering translucent black silhouettes of tube and ribbon segments (and using jitter) before calling on the halftoning shaders.
void	cacheDefaultGeometricObjects(GL gl) Uses the default values for tiling (slices and stacks) to cache geometric objects (spheres and cylinders) in the form of OpenGL display lists.
void	cacheGeometricObject(GL gl, GeometricListInfo info) Caches a new OpenGL display list for a geometric object.
void	cacheSegmentGeometry(GL gl, Model model, StyleEnum style) Calls on the SegmentReferences object to cache OpenGL display lists for the Segments of the current Model.
void	cacheTextLabels(GL gl, List<String> textLabels) Informs the TextLabelManager that OpenGL display lists for text label sub need to be cached.
void	compileShaders(GL gl) Compiles the OpenGL Shading Language vertex and fragment shaders that will be needed for lighting calculations and texture mapping.
void	draw(GL gl, Atom atom) Draws an Atom as a sphere.
void	draw(GL gl, Bond bond) Draws the Bond as a single cylinder for a Balls-and-Sticks style display, but two cylinders for a Sticks style display.
void	draw(GL gl, Drawable d) Determines if a Drawable object is an Atom, Bond, or Segment, and then calls on the appropriate draw() method.
void	draw(GL gl, Segment segment) Draws a Segment of a Region (GeneralLoop, Helix, or BetaStrand).
Vector<Texture>	getBendTextures() Returns the bend Texture objects that were created with the loadTextures() method and are intended for use with halftoning.
CylinderListInfo	getCylinderInfo(StyleEnum style) Returns the CylinderListInfo object that holds the information on an OpenGL display list for a cylinder that is currently used for drawing Bonds.
Vector<Texture>	getHalftoningTextures() Returns the Texture objects that were created with the loadTextures() method and are intended for use with halftoning.
Vector<Texture>	getPatternsTextures() Returns the Texture objects that were created with the loadTextures() method and are intended for use as patterns to apply to tubes and ribbons drawn in color (rather than halftoning).
SphereListInfo	getSphereInfo(StyleEnum style) Returns the SphereListInfo object that holds the information on an OpenGL display list for a sphere that is currently used for drawing Atoms.
StyleEnum	getStyle() Returns the current style (TUBES, RIBBONS, RIBBONS_AND_TUBES, FRENET_FRAMES, SPACE_FILLING, BALLS_AND_STICKS, or STICKS).
void	loadTextures(GL gl) Loads the default texture objects needed for text labels and real-time halftoning.
void	printAutoTilingNumbers(boolean b) If automatic tiling is in use, setting this method to true will cause the tiling numbers to be printed to standard out for testing and debugging purposes.
void	readGlyphSet() Obtains a set of glyphs by using the default '.conf' configuration file in the fonts directory.
void	setAutoTiling(boolean autoTiling) If automatic tiling is set to true, then the level of detail (tiling number) for a sphere or cylinder will be calculated based on the camera distance for each Atom or Bond, respectively.
void	setExtraLines(boolean extraLines) If tubes or ribbons are being rendered, lines will be drawn at the beginning and end of each segment if extra lines is set to true.
void	setFPSTextureAndShader(GL gl, int texName) Sets the texture object and shaders to be used when drawing an fps (frames per second) label on the canvas.
void	setStyle(StyleEnum style) Sets the style (TUBES, RIBBONS, RIBBONS_AND_TUBES, FRENET_FRAMES, SPACE_FILLING, BALLS_AND_STICKS, or STICKS).
void	toggleBlendObjectEdges() Toggles the boolean value that is set with the blendObjectsEdges() method.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AUTO_TILING

public static final boolean AUTO_TILING

Automatic tiling (level of detail) for spheres and cylinders is set to true by default.

See Also:

Constant Field Values

Constructor Detail

StructureToGraphics

public StructureToGraphics()

Constructs a StructureToGraphics object.

The style will be set to the default style in StyleEnum.

Method Detail

blendObjectEdges

public void blendObjectEdges(boolean b)

Turns on or off the ability of the halftoning shaders to soften aliasing (jagged edges) by rendering translucent black silhouettes of tube and ribbon segments (and using jitter) before calling on the halftoning shaders. This effect may be added to other shaders at a later time.

Parameters:

b - boolean value to determine if object edges should be smoothed.

toggleBlendObjectEdges

public void toggleBlendObjectEdges()

Toggles the boolean value that is set with the blendObjectsEdges() method.

setAutoTiling

public void setAutoTiling(boolean autoTiling)

If automatic tiling is set to true, then the level of detail (tiling number) for a sphere or cylinder will be calculated based on the camera distance for each Atom or Bond, respectively. If automatic tiling is set to false, then a standard sphere or cylinder will be used (and camera distance will not matter). The standard sphere or cylinder is initially set to the default value in SphereReferences or CylinderReferences, respectively, but a user is allowed to change the tiling number.

Parameters:

autoTiling - boolean value for automatic tiling.

setExtraLines

public void setExtraLines(boolean extraLines)

If tubes or ribbons are being rendered, lines will be drawn at the beginning and end of each segment if extra lines is set to true. Otherwise, lines will only be drawn at the beginning or end of a segment if it is at the very start or end of a region.

Parameters:

extraLines - boolean value for extra lines.

printAutoTilingNumbers

public void printAutoTilingNumbers(boolean b)

If automatic tiling is in use, setting this method to true will cause the tiling numbers to be printed to standard out for testing and debugging purposes.

Parameters:

b - boolean value for printing tiling numbers.

cacheDefaultGeometricObjects

public void cacheDefaultGeometricObjects(GL gl)

Uses the default values for tiling (slices and stacks) to cache geometric objects (spheres and cylinders) in the form of OpenGL display lists.

Parameters:

gl - the current GL object.

cacheGeometricObject

public void cacheGeometricObject(GL gl,
                                 GeometricListInfo info)

Caches a new OpenGL display list for a geometric object.

The GeometricListInfo objects created during initialization of the OpenGL state are expected to be reused, as usually the only change needed is to adjust the number of slices and stacks that a sphere or cylinder is composed of. Therefore, if the GeometricListInfo object given as an argument already holds the name of a valid OpenGL display list, the old display list will be deleted from graphics card memory before the new OpenGL display list is created.

Parameters:

gl - the current GL object.

info - describes the requested OpenGL display list.

cacheSegmentGeometry

public void cacheSegmentGeometry(GL gl,
                                 Model model,
                                 StyleEnum style)

Calls on the SegmentReferences object to cache OpenGL display lists for the Segments of the current Model.

This first version of this method will only cache a single OpenGL display list for each Segment object, but a future version might cache multiple display lists per Segment (with varying tiling numbers) so that the level of detail to use for a Segment could be varied with camera distance.

Parameters:

gl - the current GL object.

model - the current Model.

style - the cartoon-style (Tubes, Ribbons, or Frames).

readGlyphSet

public void readGlyphSet()
                  throws GlyphException

Obtains a set of glyphs by using the default '.conf' configuration file in the fonts directory.

Throws:

GlyphException - if a problem occurs while trying to read the set of glyphs from a file.

cacheTextLabels

public void cacheTextLabels(GL gl,
                            List<String> textLabels)

Informs the TextLabelManager that OpenGL display lists for text label sub need to be cached.

The textLabels should be a non-redundant list of the residueIDs for the AminoAcids of the Structure. These residueIDs will be used to create texture maps for pasting AminoAcid labels (such as 'A 123') onto the curved surfaces of the tubes and ribbon used for a cartoon representation of a protein structure.

Parameters:

textLabels - the text label to create a subimage for.

draw

public void draw(GL gl,
                 Drawable d)

Determines if a Drawable object is an Atom, Bond, or Segment, and then calls on the appropriate draw() method.

Parameters:

gl - the current GL object.

d - the Drawable object to draw.

draw

public void draw(GL gl,
                 Atom atom)

Draws an Atom as a sphere. The cacheSphere() method must have been called at least once before this method can be used because it will attempt to draw the sphere using an OpenGL display list, which is how the cacheSphere() method saves the OpenGL commands for drawing a sphere.

Parameters:

gl - the current GL object.

atom - the Atom to draw.

draw

public void draw(GL gl,
                 Bond bond)

Draws the Bond as a single cylinder for a Balls-and-Sticks style display, but two cylinders for a Sticks style display. The single cylinder representation uses the Bond's own color attribute, while the two cylinder representation uses the color of the source Atom for one cylinder (half bond) and the color of the destination Atom for the other cylinder.

ALGORITHM: Cylinders are always drawn with their base at the origin and their top at xyz = (0, 0, height). To reorient a cylinder according to a direction vector, add the cylinder vector (0, 0, height) to the direction vector in order to obtain a vector on the line in between the two vectors, and then rotate 180 degrees about that line.

Parameters:

gl - the current GL object.

bond - the Bond to draw.

draw

public void draw(GL gl,
                 Segment segment)

Draws a Segment of a Region (GeneralLoop, Helix, or BetaStrand).

Parameters:

gl - the current GL object.

segment - the Segment to draw.

compileShaders

public void compileShaders(GL gl)
                    throws ShaderException

Compiles the OpenGL Shading Language vertex and fragment shaders that will be needed for lighting calculations and texture mapping.

Parameters:

gl - the current GL object.

Throws:

ShaderException - if an error occurs while trying to compile and link any of the shader pairs.

loadTextures

public void loadTextures(GL gl)
                  throws TextureException

Loads the default texture objects needed for text labels and real-time halftoning.

Parameters:

gl - the current GL object.

Throws:

TextureException - if an error occurs while trying to read a texture file.

getPatternsTextures

public Vector<Texture> getPatternsTextures()

Returns the Texture objects that were created with the loadTextures() method and are intended for use as patterns to apply to tubes and ribbons drawn in color (rather than halftoning).

This method should only be called after loadTextures(gl) has already been used. However, it will never return an empty list. Even if there was a problem with the loadTextures() method, the list returned will always have at least one Texture object, the Texture with the menu name of "None".

Returns:

A list of Texture objects that can be used for halftoning.

getHalftoningTextures

public Vector<Texture> getHalftoningTextures()

Returns the Texture objects that were created with the loadTextures() method and are intended for use with halftoning.

This method should only be called after loadTextures(gl) has already been used. However, it will never return an empty list. Even if there was a problem with the loadTextures() method, the list returned will always have at least one Texture object, the Texture with the menu name of "None".

Returns:

A list of Texture objects that can be used for halftoning.

getBendTextures

public Vector<Texture> getBendTextures()

Returns the bend Texture objects that were created with the loadTextures() method and are intended for use with halftoning.

This method should only be called after loadTextures(gl) has already been used. However, it will never return an empty list. Even if there was a problem with the loadTextures() method, the list returned will always have at least one Texture object, the Texture with the menu name of "None".

Returns:

A list of Texture objects that can be used for halftoning.

getStyle

public StyleEnum getStyle()

Returns the current style (TUBES, RIBBONS, RIBBONS_AND_TUBES, FRENET_FRAMES, SPACE_FILLING, BALLS_AND_STICKS, or STICKS).
>br/> The style is not allowed to be null, so if null was given as an argument to setStyle(), the style will be the default style specified in StyleEnum.

Returns:

The style as an enum.

setStyle

public void setStyle(StyleEnum style)

Sets the style (TUBES, RIBBONS, RIBBONS_AND_TUBES, FRENET_FRAMES, SPACE_FILLING, BALLS_AND_STICKS, or STICKS).
>br/> The style is not allowed to be null, so if null is given as an argument to this method, the style will be set to the default style specified in StyleEnum.

Parameters:

style - the style as an enum.

getSphereInfo

public SphereListInfo getSphereInfo(StyleEnum style)

Returns the SphereListInfo object that holds the information on an OpenGL display list for a sphere that is currently used for drawing Atoms. There are two types of spheres cached: one for SPACE_FILLING and one for BALLS_AND_STICKS.

Returns:

The display list info object for a sphere.

getCylinderInfo

public CylinderListInfo getCylinderInfo(StyleEnum style)

Returns the CylinderListInfo object that holds the information on an OpenGL display list for a cylinder that is currently used for drawing Bonds. There are two types of cylinders cached: one for BALLS_AND_STICKS and one for STICKS.

Returns:

The display list info object for a cylinder.

setFPSTextureAndShader

public void setFPSTextureAndShader(GL gl,
                                   int texName)

Sets the texture object and shaders to be used when drawing an fps (frames per second) label on the canvas.