Package org.jmol.g3d

Class 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 Detail

      • isFullSceneAntialiasingEnabled

        private boolean isFullSceneAntialiasingEnabled
      • antialias2

        private boolean antialias2
      • stringCount

        private int stringCount
      • anaglyphChannelBytes

        private byte[] anaglyphChannelBytes
      • twoPass

        private boolean twoPass
      • haveTranslucentObjects

        private boolean haveTranslucentObjects
      • pbuf

        protected int[] pbuf
      • pbufT

        protected int[] pbufT
      • zbuf

        protected int[] zbuf
      • zbufT

        protected int[] zbufT
      • translucencyMask

        protected int translucencyMask
      • renderLow

        private boolean renderLow
      • shadesCurrent

        private int[] shadesCurrent
      • anaglyphLength

        private int anaglyphLength
      • zMargin

        protected int zMargin
      • aobuf

        private int[] aobuf
      • currentShadeIndex

        int currentShadeIndex
      • lastRawColor

        private int lastRawColor
      • translucencyLog

        int translucencyLog
      • wasScreened

        private boolean wasScreened
      • saveAmbient

        private int saveAmbient
      • saveDiffuse

        private int saveDiffuse
      • sort

        public static java.util.Comparator<TextString> sort
      • sA

        private javajs.util.P3i sA
      • sB

        private javajs.util.P3i sB
      • sC

        private javajs.util.P3i sC
      • nullShadeIndex

        private static byte nullShadeIndex
      • vectorAB

        private final javajs.util.V3 vectorAB
      • vectorAC

        private final javajs.util.V3 vectorAC
      • vectorNormal

        private final javajs.util.V3 vectorNormal
      • shadeIndexes

        private final byte[] shadeIndexes
      • shadeIndexes2Sided

        private final byte[] shadeIndexes2Sided
      • pass2Flag01

        public int pass2Flag01
    • Constructor Detail

      • Graphics3D

        public Graphics3D()
    • Method Detail

      • clear

        public void clear()
        Overrides:
        clear in class GData
      • destroy

        public void destroy()
        Overrides:
        destroy in class GData
      • setZMargin

        void setZMargin​(int dz)
      • initialize

        public void initialize​(Viewer vwr,
                               javajs.api.GenericPlatform apiPlatform)
        Overrides:
        initialize in class GData
      • getRenderer

        private G3DRenderer getRenderer​(java.lang.String type)
      • setWindowParameters

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

        public void beginRendering​(javajs.util.M3 rotationMatrix,
                                   boolean translucentMode,
                                   boolean isImageWrite,
                                   boolean renderLow)
        Overrides:
        beginRendering in class GData
        renderLow - TODO
      • releaseBuffers

        private void releaseBuffers()
      • setPass2

        public boolean setPass2​(boolean antialiasTranslucent)
        Overrides:
        setPass2 in class GData
        Returns:
        true if need a second (translucent) pass
      • mergeBufferPixel

        public static int mergeBufferPixel​(int argbA,
                                           int argbB,
                                           int bgcolor)
      • getScreenImage

        public java.lang.Object getScreenImage​(boolean isImageWrite)
        Overrides:
        getScreenImage in class GData
        Returns:
        image object
      • applyAnaglygh

        public void applyAnaglygh​(STER stereoMode,
                                  int[] stereoColors)
        Overrides:
        applyAnaglygh in class GData
      • downsampleFullSceneAntialiasing

        private void downsampleFullSceneAntialiasing​(boolean downsampleZBuffer)
      • downsample2d

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

        private static void downsample2dZ​(int[] pbuf,
                                          int[] zbuf,
                                          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
      • setScreened

        Pixelator setScreened​(boolean isScreened)
      • 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
        x - center x
        y - center y
        z - center z
      • 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
      • fillSphereI

        public void fillSphereI​(int diameter,
                                javajs.util.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,
                                   javajs.util.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​(javajs.util.P3 center,
                                  javajs.util.P3[] points,
                                  int x,
                                  int y,
                                  int z,
                                  int diameter,
                                  javajs.util.M3 mToEllipsoidal,
                                  double[] coef,
                                  javajs.util.M4 mDeriv,
                                  int selectedOctant,
                                  javajs.util.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
      • drawHLine

        private void drawHLine​(int x,
                               int y,
                               int z,
                               int w)
      • drawVLine

        private void drawVLine​(int x,
                               int y,
                               int z,
                               int h)
      • 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​(java.lang.String str,
                               javajs.awt.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​(java.lang.String str,
                                     javajs.awt.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 -
      • plotText

        public void plotText​(int x,
                             int y,
                             int z,
                             int argb,
                             int bgargb,
                             java.lang.String text,
                             javajs.awt.Font font3d,
                             JmolRendererInterface jmolRenderer)
        Overrides:
        plotText in class GData
        bgargb - TODO
      • drawImage

        public void drawImage​(java.lang.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,
                              java.lang.Object image,
                              JmolRendererInterface jmolRenderer,
                              short bgcolix,
                              int imageWidth,
                              int imageHeight)
        Overrides:
        plotImage in class GData
      • setFontFid

        public void setFontFid​(byte fid)
        Overrides:
        setFontFid in class GData
      • setFont

        public void setFont​(javajs.awt.Font font3d)
        Overrides:
        setFont in class GData
      • drawDashedLineBits

        public void drawDashedLineBits​(int run,
                                       int rise,
                                       javajs.util.P3 pointA,
                                       javajs.util.P3 pointB)
        Specified by:
        drawDashedLineBits in interface JmolRendererInterface
      • setScreeni

        private void setScreeni​(javajs.util.P3 pt,
                                javajs.util.P3i p)
      • 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,
                                 javajs.util.P3 pointA,
                                 javajs.util.P3 pointB)
        Specified by:
        drawLineBits 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,
                                         javajs.util.P3 screenA,
                                         javajs.util.P3 screenB,
                                         javajs.util.P3 pt0f,
                                         javajs.util.P3 pt1f,
                                         float radius)
        Specified by:
        fillCylinderScreen3I in interface JmolRendererInterface
      • fillCylinder

        public void fillCylinder​(byte endcaps,
                                 int diameter,
                                 javajs.util.P3i screenA,
                                 javajs.util.P3i screenB)
        Specified by:
        fillCylinder in interface JmolRendererInterface
      • fillCylinderBits

        public void fillCylinderBits​(byte endcaps,
                                     int diameter,
                                     javajs.util.P3 screenA,
                                     javajs.util.P3 screenB)
        Specified by:
        fillCylinderBits in interface JmolRendererInterface
      • fillCylinderBits2

        public void fillCylinderBits2​(short colixA,
                                      short colixB,
                                      byte endcaps,
                                      int diameter,
                                      javajs.util.P3 screenA,
                                      javajs.util.P3 screenB)
        Specified by:
        fillCylinderBits2 in interface JmolRendererInterface
      • fillConeScreen3f

        public void fillConeScreen3f​(byte endcap,
                                     int screenDiameter,
                                     javajs.util.P3 screenBase,
                                     javajs.util.P3 screenTip,
                                     boolean isBarb)
        Specified by:
        fillConeScreen3f in interface JmolRendererInterface
      • drawHermite4

        public void drawHermite4​(int tension,
                                 javajs.util.P3 s0,
                                 javajs.util.P3 s1,
                                 javajs.util.P3 s2,
                                 javajs.util.P3 s3)
        Specified by:
        drawHermite4 in interface JmolRendererInterface
      • drawHermite7

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

        public void fillHermite​(int tension,
                                int diameterBeg,
                                int diameterMid,
                                int diameterEnd,
                                javajs.util.P3 s0,
                                javajs.util.P3 s1,
                                javajs.util.P3 s2,
                                javajs.util.P3 s3)
        Specified by:
        fillHermite in interface JmolRendererInterface
      • drawTriangle3C

        public void drawTriangle3C​(javajs.util.P3i screenA,
                                   short colixA,
                                   javajs.util.P3i screenB,
                                   short colixB,
                                   javajs.util.P3i screenC,
                                   short colixC,
                                   int check)
        Specified by:
        drawTriangle3C in interface JmolRendererInterface
      • fillTriangleTwoSided

        public void fillTriangleTwoSided​(short normix,
                                         javajs.util.P3 screenA,
                                         javajs.util.P3 screenB,
                                         javajs.util.P3 screenC)
        Specified by:
        fillTriangleTwoSided in interface JmolRendererInterface
      • fillTriangleP3f

        private void fillTriangleP3f​(javajs.util.P3 screenA,
                                     javajs.util.P3 screenB,
                                     javajs.util.P3 screenC,
                                     boolean useGouraud)
      • fillTriangle3f

        public void fillTriangle3f​(javajs.util.P3 screenA,
                                   javajs.util.P3 screenB,
                                   javajs.util.P3 screenC,
                                   boolean isSolid)
        Specified by:
        fillTriangle3f in interface JmolRendererInterface
      • fillTriangle3i

        public void fillTriangle3i​(javajs.util.P3 screenA,
                                   javajs.util.P3 screenB,
                                   javajs.util.P3 screenC,
                                   javajs.util.T3 ptA,
                                   javajs.util.T3 ptB,
                                   javajs.util.T3 ptC,
                                   boolean doShade)
        Specified by:
        fillTriangle3i in interface JmolRendererInterface
      • fillTriangle3CN

        public void fillTriangle3CN​(javajs.util.P3i screenA,
                                    short colixA,
                                    short normixA,
                                    javajs.util.P3i screenB,
                                    short colixB,
                                    short normixB,
                                    javajs.util.P3i screenC,
                                    short colixC,
                                    short normixC)
        Specified by:
        fillTriangle3CN in interface JmolRendererInterface
      • fillTriangle3CNBits

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

        private boolean checkGouraud​(short colixA,
                                     short colixB,
                                     short colixC,
                                     short normixA,
                                     short normixB,
                                     short normixC)
      • getShadeIndex

        public int getShadeIndex​(short normix)
      • setTriangleTranslucency

        private void setTriangleTranslucency​(short colixA,
                                             short colixB,
                                             short colixC)
      • fillQuadrilateral

        public void fillQuadrilateral​(javajs.util.P3 screenA,
                                      javajs.util.P3 screenB,
                                      javajs.util.P3 screenC,
                                      javajs.util.P3 screenD,
                                      boolean isSolid)
        Specified by:
        fillQuadrilateral in interface JmolRendererInterface
      • plotPixelClippedArgb

        void plotPixelClippedArgb​(int argb,
                                  int x,
                                  int y,
                                  int z,
                                  int width,
                                  int[] zbuf,
                                  Pixelator p)
      • plotPixelUnclipped

        void plotPixelUnclipped​(int argb,
                                int x,
                                int y,
                                int z,
                                int width,
                                int[] zbuf,
                                Pixelator p)
      • plotImagePixel

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

        void plotPixelsClippedRaster​(int count,
                                     int x,
                                     int y,
                                     int zAtLeft,
                                     int zPastRight,
                                     Rgb16 rgb16Left,
                                     Rgb16 rgb16Right)
      • plotPixelsUnclippedRaster

        void plotPixelsUnclippedRaster​(int count,
                                       int x,
                                       int y,
                                       int zAtLeft,
                                       int zPastRight,
                                       Rgb16 rgb16Left,
                                       Rgb16 rgb16Right)
      • plotPixelsClippedRasterBits

        void plotPixelsClippedRasterBits​(int count,
                                         int x,
                                         int y,
                                         int zAtLeft,
                                         int zPastRight,
                                         Rgb16 rgb16Left,
                                         Rgb16 rgb16Right,
                                         float a,
                                         float b)
      • plotPixelsUnclippedRasterBits

        void plotPixelsUnclippedRasterBits​(int count,
                                           int x,
                                           int y,
                                           Rgb16 rgb16Left,
                                           Rgb16 rgb16Right,
                                           float a,
                                           float b)
      • plotPixelsUnclippedCount

        void plotPixelsUnclippedCount​(int c,
                                      int count,
                                      int x,
                                      int y,
                                      int z,
                                      int width,
                                      int[] zbuf,
                                      Pixelator p)
      • plotPoints

        private void plotPoints​(int count,
                                int[] coordinates,
                                int xOffset,
                                int yOffset)
      • setColorNoisy

        void setColorNoisy​(int shadeIndex)
      • getShadeIndexP3

        private int getShadeIndexP3​(javajs.util.P3 screenA,
                                    javajs.util.P3 screenB,
                                    javajs.util.P3 screenC,
                                    boolean isSolid)
      • canDoTriangles

        public boolean canDoTriangles()
      • isCartesianExport

        public boolean isCartesianExport()
      • drawBond

        public void drawBond​(javajs.util.P3 atomA,
                             javajs.util.P3 atomB,
                             short colixA,
                             short colixB,
                             byte endcaps,
                             short mad,
                             int bondOrder)
        Specified by:
        drawBond in interface JmolRendererInterface
      • drawEllipse

        public boolean drawEllipse​(javajs.util.P3 ptAtom,
                                   javajs.util.P3 ptX,
                                   javajs.util.P3 ptY,
                                   boolean fillArc,
                                   boolean wireframeOnly)
        Specified by:
        drawEllipse in interface JmolRendererInterface
      • getPrivateKey

        public double getPrivateKey()
      • setRotationMatrix

        public void setRotationMatrix​(javajs.util.M3 rotationMatrix)
      • renderCrossHairs

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

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