Class Graphics3D

java.lang.Object
org.jmol.util.GData
org.jmol.g3d.Graphics3D
All Implemented Interfaces:
JmolGraphicsInterface, JmolRendererInterface
public final class Graphics3D extends GData implements JmolRendererInterface
Provides high-level graphics primitives for 3D visualization for the software renderers. These methods should not have to be used with WebGL or OpenGL or other hardware accelerators. This module is linked to via reflection from org.jmol.viewer.Viewer Bob Hanson 9/2/2012 Note added 4/2015 BH: Well, it turns out that the calculation of the intermediate pixel z value in all methods involving rasterization of lines is incorrect and has been incorrect since Jmol's inception. I noticed long ago that large triangles such as produced in DRAW could incorrectly overlay/underlay other objects, but I could never determine why. It turns out that the assumption that z-value is linear across a line when perspectiveDepth is TRUE is simply incorrect. Basically, the function z(x) is non-linear. Treating it as simply a linear function results in oddities where lines and planes -- particularly created using DRAW and large distances -- appear to be where they are not. Through Jmol 13.3.13 we had the standard linear relationship: z = (x - xa) / (xb - xa) * (zb - za) + za I worked it out, and, amazingly, it should be z = (xb - xa) * za * zb / ((xb - x) * zb + (x - xa) * za) Note that it is still true that when x = xb, z = zb and when x = xa, z = za, as required. This equation can be rearranged to z = a / (b - x) where a = (xb - xa) * za * (zb / (zb - za)) and b = (xb * zb - xa * za) / (zb - za) These values must be floats, not integers, to work properly, because these are extrapolations from long distances in some cases. So there is considerable overhead there. It will take some experimentation to figure this out. The practical implications are for line, cylinder, and triangle drawing. First-pass corrections are for axes and DRAW objects. They tend to be the larger objects that result in the issue. Also affected is POV-Ray output, because right now POV-Ray is created using perspective on and plotted as though it were orthographic, but although that works in x and y, it does not work in z!

A pure software implementation of a 3D graphics engine. No hardware required. Depending upon what you are rendering ... some people say it is pretty fast.

Author:
Miguel, miguel@jmol.org with additions by Bob Hanson hansonr@stolaf.edu The above is an understatement to say the least. This is a two-pass rendering system. In the first pass, all opaque objects are rendered. In the second pass, all translucent objects are rendered. If there are no translucent objects, then that is found in the first pass as follows: The renderers first try to set the color index of the object to be rendered using setColix(short colix), and that method returns false if we are in the wrong pass for that type of object. In addition, setColix records in the boolean haveTranslucentObjects whether a translucent object was seen in the first pass. The second pass is skipped if this flag is not set. This saves immensely on rendering time when there are no translucent objects. THUS, IT IS CRITICAL THAT ALL RENDERING OPTIONS CHECK THE COLIX USING g3d.setColix(short colix) PRIOR TO RENDERING. Translucency is rendered only approximately. We can't maintain a full buffer of all translucent objects. Instead, we "cheat" by maintaining one translucent z buffer. When a translucent pixel is to be written, its z position is checked and... ...if it is behind or at the z position of any pixel, it is ignored ...if it is in front of a translucent pixel, it is added to the translucent buffer ...if it is between an opaque and translucent pixel, the translucent pixel is turned opaque, and the new pixel is added to the translucent buffer This guarantees accurate translucency when there are no more than two translucent pixels between the user and an opaque pixel. It's a fudge, for sure. But it is pretty good, and certainly fine for "draft" work. Users needing more accurate translucencty are encouraged to use the POV-Ray export facility for production-level work. Antialiasing is accomplished as full scene antialiasing. This means that the width and height are doubled (both here and in TransformManager), the scene is rendered, and then each set of four pixels is averaged (roughly) as the final pixel in the width*height buffer. Antialiasing options allow for antialiasing of all objects: antialiasDisplay = true antialiasTranslucent = true or just the opaque ones: antialiasDisplay = true antialiasTranslucent = false or not at all: antialiasDisplay = false The difference will be speed and memory. Adding translucent objects doubles the buffer requirement, and adding antialiasing quadruples the buffer requirement. So we have: Memory requirements are significant, in multiples of (width) * (height) 32-bit integers: antialias OFF ON/opaque only ON/all objects no translucent 1p + 1z = 2 4p + 4z = 8 4p + 4z = 8 objects with translucent 2p + 2z = 4 5p + 5z = 10 8p + 8z = 16 objects Note that no antialising at all is required for POV-Ray output. POV-Ray will do antialiasing on its own. In principle we could save a bit in the case of antialiasing of just opaque objects and reuse the p and z buffers for the translucent buffer, but this hasn't been implemented because the savings isn't that great, and if you are going to the trouble of having antialiasing, you probably what it all.

  • Field Details

    • pbuf

      protected int[] pbuf

    • pbufT

      protected int[] pbufT

    • zbuf

      protected int[] zbuf

    • zbufT

      protected int[] zbufT

    • translucencyMask

      protected int translucencyMask

    • zMargin

      protected int zMargin

    • sort

      public static Comparator<org.jmol.g3d.TextString> sort

    • pass2Flag01

      public int pass2Flag01

  • Constructor Details

    • Graphics3D

      public Graphics3D()

  • Method Details

    • isWebGL

      public boolean isWebGL()
      Specified by:
      isWebGL in interface JmolRendererInterface

    • clear

      public void clear()
      Overrides:
      clear in class GData

    • destroy

      public void destroy()
      Overrides:
      destroy in class GData

    • initialize

      public void initialize(Viewer vwr, GenericPlatform apiPlatform)
      Overrides:
      initialize in class GData

    • addRenderer

      public void addRenderer(int tok)
      allows core JavaScript loading to not involve these classes
      Specified by:
      addRenderer in interface JmolRendererInterface
      Overrides:
      addRenderer in class GData
      Parameters:
      tok -

    • setWindowParameters

      public void setWindowParameters(int width, int height, boolean antialias)
      Overrides:
      setWindowParameters in class GData

    • checkTranslucent

      public boolean checkTranslucent(boolean isAlphaTranslucent)
      Specified by:
      checkTranslucent in interface JmolRendererInterface

    • beginRendering

      public void beginRendering(M3 rotationMatrix, boolean translucentMode, boolean isImageWrite, boolean renderLow)
      Overrides:
      beginRendering in class GData
      Parameters:
      rotationMatrix -
      translucentMode -
      isImageWrite -
      renderLow - TODO

    • setBackgroundTransparent

      public void setBackgroundTransparent(boolean TF)
      Overrides:
      setBackgroundTransparent in class GData
      Parameters:
      TF -

    • setPass2

      public boolean setPass2(boolean antialiasTranslucent)
      Overrides:
      setPass2 in class GData
      Parameters:
      antialiasTranslucent -
      Returns:
      true if need a second (translucent) pass

    • endRendering

      public void endRendering()
      Overrides:
      endRendering in class GData

    • mergeBufferPixel

      public static int mergeBufferPixel(int argbA, int argbB, int bgcolor)

    • getScreenImage

      public Object getScreenImage(boolean isImageWrite)
      Overrides:
      getScreenImage in class GData
      Parameters:
      isImageWrite -
      Returns:
      image object

    • applyAnaglygh

      public void applyAnaglygh(STER stereoMode, int[] stereoColors)
      Overrides:
      applyAnaglygh in class GData
      Parameters:
      stereoMode -
      stereoColors -

    • snapshotAnaglyphChannelBytes

      public void snapshotAnaglyphChannelBytes()
      Overrides:
      snapshotAnaglyphChannelBytes in class GData

    • releaseScreenImage

      public void releaseScreenImage()
      Overrides:
      releaseScreenImage in class GData

    • haveTranslucentObjects

      public boolean haveTranslucentObjects()
      Specified by:
      haveTranslucentObjects in interface JmolRendererInterface

    • setSlabAndZShade

      public void setSlabAndZShade(int slabValue, int depthValue, int zSlab, int zDepth, int zShadePower)
      Specified by:
      setSlabAndZShade in interface JmolGraphicsInterface
      Overrides:
      setSlabAndZShade in class GData
      Parameters:
      zSlab - for zShade
      zDepth - for zShade
      zShadePower -

    • downsample2d

      public static void downsample2d(int[] pbuf, int width, int height, int bgcheck)

    • hasContent

      public boolean hasContent()

    • setC

      public boolean setC(short colix)
      sets current color from colix color index
      Specified by:
      setC in interface JmolRendererInterface
      Overrides:
      setC in class GData
      Parameters:
      colix - the color index
      Returns:
      true or false if this is the right pass

    • drawFilledCircle

      public void drawFilledCircle(short colixRing, short colixFill, int diameter, int x, int y, int z)
      Description copied from interface: JmolRendererInterface
      draws a ring and filled circle (halos, draw CIRCLE, draw handles)
      Specified by:
      drawFilledCircle in interface JmolRendererInterface
      Parameters:
      colixRing -
      colixFill -
      diameter -
      x - center x
      y - center y
      z - center z

    • volumeRender4

      public void volumeRender4(int diameter, int x, int y, int z)
      Specified by:
      volumeRender4 in interface JmolRendererInterface

    • fillSphereXYZ

      public void fillSphereXYZ(int diameter, int x, int y, int z)
      fills a solid sphere
      Specified by:
      fillSphereXYZ in interface JmolRendererInterface
      Parameters:
      diameter - pixel count
      x - center x
      y - center y
      z - center z

    • volumeRender

      public void volumeRender(boolean TF)
      Specified by:
      volumeRender in interface JmolRendererInterface

    • fillSphereI

      public void fillSphereI(int diameter, P3i center)
      fills a solid sphere
      Specified by:
      fillSphereI in interface JmolRendererInterface
      Parameters:
      diameter - pixel count
      center - javax.vecmath.Point3i defining the center

    • fillSphereBits

      public void fillSphereBits(int diameter, P3 center)
      fills a solid sphere
      Specified by:
      fillSphereBits in interface JmolRendererInterface
      Parameters:
      diameter - pixel count
      center - a javax.vecmath.Point3f ... floats are casted to ints

    • fillEllipsoid

      public void fillEllipsoid(P3 center, P3[] points, int x, int y, int z, int diameter, M3 mToEllipsoidal, double[] coef, M4 mDeriv, int selectedOctant, P3[] octantPoints)
      Specified by:
      fillEllipsoid in interface JmolRendererInterface

    • drawRect

      public void drawRect(int x, int y, int z, int zSlab, int rWidth, int rHeight)
      draws a rectangle
      Specified by:
      drawRect in interface JmolRendererInterface
      Parameters:
      x - upper left x
      y - upper left y
      z - upper left z
      zSlab - z for slab check (for set labelsFront)
      rWidth - pixel count
      rHeight - pixel count

    • fillTextRect

      public void fillTextRect(int x, int y, int z, int zSlab, int widthFill, int heightFill)
      fills background rectangle for label

      Specified by:
      fillTextRect in interface JmolRendererInterface
      Parameters:
      x - upper left x
      y - upper left y
      z - upper left z
      zSlab - z value for slabbing
      widthFill - pixel count
      heightFill - pixel count

    • drawString

      public void drawString(String str, Font font3d, int xBaseline, int yBaseline, int z, int zSlab, short bgColix)
      draws the specified string in the current font. no line wrapping -- axis, labels, measures
      Specified by:
      drawString in interface JmolRendererInterface
      Parameters:
      str - the String
      font3d - the Font3D
      xBaseline - baseline x
      yBaseline - baseline y
      z - baseline z
      zSlab - z for slab calculation
      bgColix -

    • drawStringNoSlab

      public void drawStringNoSlab(String str, Font font3d, int xBaseline, int yBaseline, int z, short bgColix)
      draws the specified string in the current font. no line wrapping -- echo, frank, hover, molecularOrbital, uccage
      Specified by:
      drawStringNoSlab in interface JmolRendererInterface
      Parameters:
      str - the String
      font3d - the Font3D
      xBaseline - baseline x
      yBaseline - baseline y
      z - baseline z
      bgColix -

    • renderAllStrings

      public void renderAllStrings(Object jmolRenderer)
      Specified by:
      renderAllStrings in interface JmolGraphicsInterface
      Overrides:
      renderAllStrings in class GData

    • plotText

      public void plotText(int x, int y, int z, int argb, int bgargb, String text, Font font3d, JmolRendererInterface jmolRenderer)
      Overrides:
      plotText in class GData
      Parameters:
      x -
      y -
      z -
      argb -
      bgargb - TODO
      text -
      font3d -
      jmolRenderer -

    • drawImage

      public void drawImage(Object objImage, int x, int y, int z, int zSlab, short bgcolix, int width, int height)
      Specified by:
      drawImage in interface JmolRendererInterface

    • plotImage

      public void plotImage(int x, int y, int z, Object image, JmolRendererInterface jmolRenderer, short bgcolix, int imageWidth, int imageHeight)
      Overrides:
      plotImage in class GData
      Parameters:
      x -
      y -
      z -
      image -
      jmolRenderer -
      bgcolix -
      imageWidth -
      imageHeight -

    • setFont

      public void setFont(Font font3d)
      Overrides:
      setFont in class GData
      Parameters:
      font3d -

    • drawPixel

      public void drawPixel(int x, int y, int z)
      Specified by:
      drawPixel in interface JmolRendererInterface

    • drawPoints

      public void drawPoints(int count, int[] coordinates, int scale)
      Specified by:
      drawPoints in interface JmolRendererInterface

    • drawDashedLineBits

      public void drawDashedLineBits(int run, int rise, P3 pointA, P3 pointB)
      Specified by:
      drawDashedLineBits in interface JmolRendererInterface

    • drawLineABBits

      public void drawLineABBits(int run, int rise, boolean andClip)

    • drawLineXYZ

      public void drawLineXYZ(int x1, int y1, int z1, int x2, int y2, int z2)
      Specified by:
      drawLineXYZ in interface JmolRendererInterface

    • drawLine

      public void drawLine(short colixA, short colixB, int x1, int y1, int z1, int x2, int y2, int z2)
      Specified by:
      drawLine in interface JmolRendererInterface

    • drawLineBits

      public void drawLineBits(short colixA, short colixB, P3 pointA, P3 pointB)
      Specified by:
      drawLineBits in interface JmolRendererInterface

    • drawLinePixels

      public void drawLinePixels(P3i a, P3i b, int z, int zslab)
      Specified by:
      drawLinePixels in interface JmolGraphicsInterface
      Overrides:
      drawLinePixels in class GData

    • drawLineAB

      public void drawLineAB(P3 pointA, P3 pointB)
      Specified by:
      drawLineAB in interface JmolRendererInterface

    • fillCylinderXYZ

      public void fillCylinderXYZ(short colixA, short colixB, byte endcaps, int diameter, int xA, int yA, int zA, int xB, int yB, int zB)
      Specified by:
      fillCylinderXYZ in interface JmolRendererInterface

    • fillCylinderScreen3I

      public void fillCylinderScreen3I(byte endcaps, int diameter, P3 screenA, P3 screenB, P3 pt0f, P3 pt1f, float radius)
      Specified by:
      fillCylinderScreen3I in interface JmolRendererInterface

    • fillCylinder

      public void fillCylinder(byte endcaps, int diameter, P3i screenA, P3i screenB)
      Specified by:
      fillCylinder in interface JmolRendererInterface

    • fillCylinderBits

      public void fillCylinderBits(byte endcaps, int diameter, P3 screenA, P3 screenB)
      Specified by:
      fillCylinderBits in interface JmolRendererInterface

    • fillCylinderBits2

      public void fillCylinderBits2(short colixA, short colixB, byte endcaps, int diameter, P3 screenA, P3 screenB)
      Specified by:
      fillCylinderBits2 in interface JmolRendererInterface

    • fillConeScreen3f

      public void fillConeScreen3f(byte endcap, int screenDiameter, P3 screenBase, P3 screenTip, boolean isBarb)
      Specified by:
      fillConeScreen3f in interface JmolRendererInterface

    • drawHermite4

      public void drawHermite4(int tension, P3 s0, P3 s1, P3 s2, P3 s3)
      Specified by:
      drawHermite4 in interface JmolRendererInterface

    • drawHermite7

      public void drawHermite7(boolean fill, boolean border, int tension, P3 s0, P3 s1, P3 s2, P3 s3, P3 s4, P3 s5, P3 s6, P3 s7, int aspectRatio, short colixBack)
      Specified by:
      drawHermite7 in interface JmolRendererInterface

    • fillHermite

      public void fillHermite(int tension, int diameterBeg, int diameterMid, int diameterEnd, P3 s0, P3 s1, P3 s2, P3 s3)
      Specified by:
      fillHermite in interface JmolRendererInterface

    • drawTriangle3C

      public void drawTriangle3C(P3i screenA, short colixA, P3i screenB, short colixB, P3i screenC, short colixC, int check)
      Specified by:
      drawTriangle3C in interface JmolRendererInterface

    • fillTriangleTwoSided

      public void fillTriangleTwoSided(short normix, P3 screenA, P3 screenB, P3 screenC)
      Specified by:
      fillTriangleTwoSided in interface JmolRendererInterface

    • fillTriangle3f

      public void fillTriangle3f(P3 screenA, P3 screenB, P3 screenC, boolean isSolid)
      Specified by:
      fillTriangle3f in interface JmolRendererInterface

    • fillTriangle3i

      public void fillTriangle3i(P3 screenA, P3 screenB, P3 screenC, T3 ptA, T3 ptB, T3 ptC, boolean doShade)
      Specified by:
      fillTriangle3i in interface JmolRendererInterface

    • fillTriangle3CN

      public void fillTriangle3CN(P3i screenA, short colixA, short normixA, P3i screenB, short colixB, short normixB, P3i screenC, short colixC, short normixC)
      Specified by:
      fillTriangle3CN in interface JmolRendererInterface

    • fillTriangle3CNBits

      public void fillTriangle3CNBits(P3 screenA, short colixA, short normixA, P3 screenB, short colixB, short normixB, P3 screenC, short colixC, short normixC, boolean twoSided)
      Specified by:
      fillTriangle3CNBits in interface JmolRendererInterface

    • getShadeIndex

      public int getShadeIndex(short normix)

    • fillQuadrilateral

      public void fillQuadrilateral(P3 screenA, P3 screenB, P3 screenC, P3 screenD, boolean isSolid)
      Specified by:
      fillQuadrilateral in interface JmolRendererInterface

    • drawSurface

      public void drawSurface(MeshSurface meshSurface, short colix)
      Specified by:
      drawSurface in interface JmolRendererInterface

    • plotPixelClippedP3i

      public void plotPixelClippedP3i(P3i screen)
      Specified by:
      plotPixelClippedP3i in interface JmolRendererInterface

    • plotImagePixel

      public void plotImagePixel(int argb, int x, int y, int z, byte shade, int bgargb, int width, int height, int[] zbuf, Object p, int transpLog)
      Specified by:
      plotImagePixel in interface JmolRendererInterface

    • renderBackground

      public void renderBackground(JmolRendererInterface jmolRenderer)
      ///////////////////////////////////////////////////////
      Specified by:
      renderBackground in interface JmolRendererInterface
      Overrides:
      renderBackground in class GData
      Parameters:
      jmolRenderer -

    • drawAtom

      public void drawAtom(Atom atom, float radius)
      Specified by:
      drawAtom in interface JmolRendererInterface

    • getExportType

      public int getExportType()
      Specified by:
      getExportType in interface JmolRendererInterface

    • getExportName

      public String getExportName()
      Specified by:
      getExportName in interface JmolRendererInterface

    • canDoTriangles

      public boolean canDoTriangles()

    • isCartesianExport

      public boolean isCartesianExport()

    • initializeExporter

      public JmolRendererInterface initializeExporter(Viewer vwr, double privateKey, GData g3d, Map<String,Object> params)
      Specified by:
      initializeExporter in interface JmolRendererInterface

    • finalizeOutput

      public String finalizeOutput()
      Specified by:
      finalizeOutput in interface JmolRendererInterface

    • drawBond

      public void drawBond(P3 atomA, P3 atomB, short colixA, short colixB, byte endcaps, short mad, int bondOrder)
      Specified by:
      drawBond in interface JmolRendererInterface

    • drawEllipse

      public boolean drawEllipse(P3 ptAtom, P3 ptX, P3 ptY, boolean fillArc, boolean wireframeOnly)
      Specified by:
      drawEllipse in interface JmolRendererInterface

    • getPrivateKey

      public double getPrivateKey()

    • clearFontCache

      public void clearFontCache()
      Overrides:
      clearFontCache in class GData

    • setRotationMatrix

      public void setRotationMatrix(M3 rotationMatrix)

    • renderCrossHairs

      public void renderCrossHairs(int[] minMax, int screenWidth, int screenHeight, P3 navOffset, float navDepth)
      Specified by:
      renderCrossHairs in interface JmolRendererInterface
      Parameters:
      minMax -
      screenWidth -
      screenHeight -
      navOffset -
      navDepth -

    • initializeOutput

      public boolean initializeOutput(Viewer vwr, double privateKey, Map<String,Object> params)
      Specified by:
      initializeOutput in interface JmolRendererInterface

    • fixTextImageRGB

      public static int fixTextImageRGB(int argb)