<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang=""> <head> <meta charset="utf-8" /> <meta name="generator" content="pandoc" /> <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" /> <title>OpenGL_API_Divergence.md</title> <style> div#header, header { border-bottom: 1px solid #aaa; margin-bottom: 0.5em; } .title { text-align: center; } .author, .date { text-align: center; } div#TOC, nav#TOC { border-bottom: 1px solid #aaa; margin-bottom: 0.5em; } nav#TOC { margin-bottom: var(--line-height); padding-bottom: 0.5rem; } nav#TOC input { display: none; } nav#TOC label { color: var(--color-link); cursor: pointer; } nav#TOC > ul { display: none; } nav#TOC > input:checked + ul { display: block; } @media print { div#TOC, nav#TOC { display: none; } } div.content { color: #111111; font-size: 14px; line-height: 1.6; } div#cgit a { color: #1212a0; } div#cgit a.sourceLine { color: #111111; } h1, h2, h3, h4, h5, h6 { font-family: "Helvetica Neue", Helvetica, "Liberation Sans", Calibri, Arial, sans-serif; page-break-after: avoid; margin: 20px 0 10px; padding: 0; } h2 { border-bottom: 1px solid #ccc; } div div { } section section { margin-left: 2em; } p {} blockquote { font-style: italic; } li { } li > p { margin-top: 1em; } ul { } ul li { } ol { } ol li { } hr {} sub { } sup { } em { } em > em { font-style: normal; } strong { } a { text-decoration: none; } @media screen { a:hover { text-decoration: underline; } } @media print { a { color: black; background: transparent; } a[href^="http://"]:after, a[href^="https://"]:after { content: " (" attr(href) ") "; font-size: 90%; } } img { vertical-align: middle; } div.figure { margin-left: auto; margin-right: auto; text-align: center; font-style: italic; } p.caption { } pre, code { background-color: #f8f8f8; white-space: pre-wrap; white-space: -moz-pre-wrap !important; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word; } pre { padding: 0.5em; border-radius: 5px; background-color: #f8f8f8; border: 1px solid #ccc; font-size: 13px; line-height: 19px; overflow: auto; padding: 6px 10px; margin-left: 0.5em; margin-right: 0.5em; } @media screen { pre { white-space: pre; overflow: auto; border: 1px dotted #777; } } code { } p > code, li > code { padding-left: 2px; padding-right: 2px; } li > p code { padding: 2px; } span.math { } div.math { } span.LaTeX { } eq { } table { border-collapse: collapse; border-spacing: 0; margin-left: auto; margin-right: auto; } thead { border-bottom: 1pt solid #000; background-color: #eee; } tr.header { } tbody { } tr { } tr.odd:hover, tr.even:hover { background-color: #eee; } tr.odd {} tr.even {} td, th { vertical-align: top; vertical-align: baseline; padding-left: 0.5em; padding-right: 0.5em; padding-top: 0.2em; padding-bottom: 0.2em; } th { font-weight: bold; } tfoot { } caption { caption-side: top; border: none; font-size: 0.9em; font-style: italic; text-align: center; margin-bottom: 0.3em; padding-bottom: 0.2em; } dl { border-top: 2pt solid black; padding-top: 0.5em; border-bottom: 2pt solid black; } dt { font-weight: bold; } dd+dt { border-top: 1pt solid black; padding-top: 0.5em; } dd { margin-bottom: 0.5em; } dd+dd { border-top: 1px solid black; } a.footnote, a.footnoteRef { font-size: small; vertical-align: text-top; } a[href^="#fnref"], a.reversefootnote { } @media print { a[href^="#fnref"], a.reversefootnote { display: none; } } div.footnotes { } div.footnotes li[id^="fn"] { } @media print { .noprint { display:none; } } </style> </head> <body> <nav id="TOC" role="doc-toc"> <strong>Contents</strong><label for="contents">⊕</label> <input type="checkbox" id="contents"> <ul> <li><a href="#jogl-and-opengl-divergence">JOGL and OpenGL Divergence</a> <ul> <li><a href="#overview">Overview</a> <ul> <li><a href="#opengl-debugging">OpenGL Debugging</a></li> <li><a href="#retrieve-mapped-buffers-data">Retrieve Mapped Buffer's Data</a></li> </ul></li> <li><a href="#references">References</a></li> </ul></li> </ul> </nav> <style> table, th, td { border: 1px solid black; } </style> <h1 id="jogl-and-opengl-divergence">JOGL and OpenGL Divergence</h1> <h2 id="overview">Overview</h2> <p>As described in <a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/overview-summary.html#overview_description">mapping of OpenGL profiles to interfaces</a>, JOGL is mostly API compatible with the OpenGL API while packaging functionality in <a href="https://jogamp.org/jogl/doc/uml/html/index-withframe.html">OpenGL profiles</a>.</p> <p>However, there are certain aspects where JOGL diverges due to managed code aspects and the Java™ language.</p> <h3 id="opengl-debugging">OpenGL Debugging</h3> <p>In 2009-2012 the <a href="https://www.khronos.org/opengl/wiki/Debug_Output">Debug Output</a> extensions <a href="http://www.opengl.org/registry/specs/AMD/debug_output.txt">AMD_debug_output</a> and <a href="https://registry.khronos.org/OpenGL/extensions/ARB/ARB_debug_output.txt">ARB_debug_output</a> were created, subsumed to the core via <a href="https://registry.khronos.org/OpenGL/extensions/KHR/KHR_debug.txt">KHR_debug</a>.</p> <p>They allow applications to <a href="https://docs.gl/gl4/glDebugMessageCallback">enable and control low-level debugging</a> using the OpenGL implementation.</p> <p>These extensions have been subsumed in <a href="https://www.khronos.org/opengl/wiki/GLAPI/glDebugMessageCallback">OpenGL 4.3</a> and in <a href="https://registry.khronos.org/OpenGL-Refpages/es3/html/glDebugMessageCallback.xhtml">OpenGL ES 3.2</a>.</p> <p>In JOGL a user may attached a <a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLDebugListener.html">GLDebugListener</a> to the <a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLContext.html">GLContext</a> via <a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLContext.html#addGLDebugListener(com.jogamp.opengl.GLDebugListener)">addGLDebugListener(..)</a>. The GLDebugListener receives the native <a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLDebugMessage.html">GLDebugMessage</a> if debugging is enabled.</p> <p>To enable debugging, the GLContext must be created having <a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLContext.html#CTX_OPTION_DEBUG">CTX_OPTION_DEBUG</a> set via <code>setContextCreationFlags(int)</code> on the <a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLContext.html#setContextCreationFlags(int)">GLContext</a> or <a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLAutoDrawable.html#setContextCreationFlags(int)">GLAutoDrawable</a>. Alternatively, <a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLContext.html#enableGLDebugMessage(boolean)">GLContext.enableGLDebugMessage(boolean</a> may be used.</p> <p>Test cases</p> <ul> <li><a href="https://jogamp.org/cgit/jogl.git/tree/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestGLDebug00NEWT.java">TestGLDebug00NEWT</a></li> <li><a href="https://jogamp.org/cgit/jogl.git/tree/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestGLDebug01NEWT.java">TestGLDebug01NEWT</a></li> </ul> <h3 id="retrieve-mapped-buffers-data">Retrieve Mapped Buffer's Data</h3> <p>Since OpenGL 1.5, a mapped buffer object's data can be retrieved via <a href="https://www.khronos.org/opengl/wiki/GLAPI/glGetBufferPointer">glGetBufferPointerv(..)</a>, i.e. the client's memory pointer.</p> <p>In JOGL, buffers are tracked via <a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLBufferStorage.html">GLBufferStorage</a>, covering the storage size, NIO client memory reference if mapped and usage flags. This ensures lifecycle alignment of the native NIO Java client memory with OpenGL buffer semantics.</p> <p>To retrieve the bound buffer you may use <a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLBase.html#getBoundBuffer(int)">getBoundBuffer(..)</a> and <a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLBase.html#getBufferStorage(int)">getBufferStorage(..)</a>.</p> <p>Tracker Implementation</p> <ul> <li><a href="https://jogamp.org/cgit/jogl.git/tree/src/jogl/classes/jogamp/opengl/GLBufferObjectTracker.java">GLBufferObjectTracker</a></li> <li><a href="https://jogamp.org/cgit/jogl.git/tree/src/jogl/classes/jogamp/opengl/GLBufferStateTracker.java">GLBufferStateTracker</a></li> </ul> <p>Test Cases</p> <ul> <li><a href="https://jogamp.org/cgit/jogl.git/tree/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestMapBufferRead01NEWT.java">TestMapBufferRead01NEWT</a></li> <li><a href="https://jogamp.org/cgit/jogl.git/tree/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestMapBufferRead02NEWT.java">TestMapBufferRead02NEWT</a></li> </ul> <h2 id="references">References</h2> <ul> <li><a href="https://jogamp.org/">JogAmp Home</a></li> <li><a href="https://jogamp.org/cgit/jogl.git/about/">JOGL Git Repo</a></li> <li><a href="https://jogamp.org/jogl/www/">JOGL Home</a></li> <li><a href="https://jogamp.org/jogl/doc/Overview-OpenGL-Evolution-And-JOGL.html">OpenGL Evolution & JOGL</a></li> <li><a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/overview-summary.html#overview_description">Mapping of OpenGL Profiles to Interfaces</a> <ul> <li><a href="https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/overview-summary.html#GLAPIInclusionCriteria">OpenGL API Inclusion Criteria</a></li> <li><a href="https://jogamp.org/jogl/doc/uml/html/index-withframe.html">UML Diagram</a></li> </ul></li> <li><a href="https://jogamp.org/jogl/doc/HowToBuild.html">How To Build</a></li> </ul> </body> </html>