diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/OpenGL_API_Divergence.html | 540 | ||||
| -rw-r--r-- | doc/OpenGL_API_Divergence.md | 61 |
2 files changed, 601 insertions, 0 deletions
diff --git a/doc/OpenGL_API_Divergence.html b/doc/OpenGL_API_Divergence.html new file mode 100644 index 000000000..5095e662a --- /dev/null +++ b/doc/OpenGL_API_Divergence.html @@ -0,0 +1,540 @@ +<!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> diff --git a/doc/OpenGL_API_Divergence.md b/doc/OpenGL_API_Divergence.md new file mode 100644 index 000000000..6cfe2fdd3 --- /dev/null +++ b/doc/OpenGL_API_Divergence.md @@ -0,0 +1,61 @@ +<style> +table, th, td { + border: 1px solid black; +} +</style> + +# JOGL and OpenGL Divergence + +## Overview +As described in [mapping of OpenGL profiles to interfaces](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/overview-summary.html#overview_description), JOGL is mostly API compatible with the OpenGL API while packaging functionality in [OpenGL profiles](https://jogamp.org/jogl/doc/uml/html/index-withframe.html). + +However, there are certain aspects where JOGL diverges due to managed code aspects and the Java™ language. + +### OpenGL Debugging +In 2009-2012 the [Debug Output](https://www.khronos.org/opengl/wiki/Debug_Output) extensions +[AMD_debug_output](http://www.opengl.org/registry/specs/AMD/debug_output.txt) and +[ARB_debug_output](https://registry.khronos.org/OpenGL/extensions/ARB/ARB_debug_output.txt) were created, +subsumed to the core via [KHR_debug](https://registry.khronos.org/OpenGL/extensions/KHR/KHR_debug.txt). + +They allow applications to [enable and control low-level debugging](https://docs.gl/gl4/glDebugMessageCallback) +using the OpenGL implementation. + +These extensions have been subsumed in [OpenGL 4.3](https://www.khronos.org/opengl/wiki/GLAPI/glDebugMessageCallback) +and in [OpenGL ES 3.2](https://registry.khronos.org/OpenGL-Refpages/es3/html/glDebugMessageCallback.xhtml). + +In JOGL a user may attached a [GLDebugListener](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLDebugListener.html) +to the [GLContext](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLContext.html) via [addGLDebugListener(..)](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLContext.html#addGLDebugListener\(com.jogamp.opengl.GLDebugListener\)). +The GLDebugListener receives the native [GLDebugMessage](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLDebugMessage.html) if debugging is enabled. + +To enable debugging, the GLContext must be created having [CTX_OPTION_DEBUG](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLContext.html#CTX_OPTION_DEBUG) set via `setContextCreationFlags(int)` on the [GLContext](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLContext.html#setContextCreationFlags\(int\)) or [GLAutoDrawable](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLAutoDrawable.html#setContextCreationFlags(int)). +Alternatively, [GLContext.enableGLDebugMessage(boolean](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLContext.html#enableGLDebugMessage\(boolean\)) may be used. + +Test cases +- [TestGLDebug00NEWT](https://jogamp.org/cgit/jogl.git/tree/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestGLDebug00NEWT.java) +- [TestGLDebug01NEWT](https://jogamp.org/cgit/jogl.git/tree/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestGLDebug01NEWT.java) + +### Retrieve Mapped Buffer's Data +Since OpenGL 1.5, a mapped buffer object's data can be retrieved via [glGetBufferPointerv(..)](https://www.khronos.org/opengl/wiki/GLAPI/glGetBufferPointer), i.e. the client's memory pointer. + +In JOGL, buffers are tracked via [GLBufferStorage](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLBufferStorage.html), 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. + +To retrieve the bound buffer you may use [getBoundBuffer(..)](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLBase.html#getBoundBuffer\(int\)) and [getBufferStorage(..)](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLBase.html#getBufferStorage\(int\)). + +Tracker Implementation +- [GLBufferObjectTracker](https://jogamp.org/cgit/jogl.git/tree/src/jogl/classes/jogamp/opengl/GLBufferObjectTracker.java) +- [GLBufferStateTracker](https://jogamp.org/cgit/jogl.git/tree/src/jogl/classes/jogamp/opengl/GLBufferStateTracker.java) + +Test Cases +- [TestMapBufferRead01NEWT](https://jogamp.org/cgit/jogl.git/tree/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestMapBufferRead01NEWT.java) +- [TestMapBufferRead02NEWT](https://jogamp.org/cgit/jogl.git/tree/src/test/com/jogamp/opengl/test/junit/jogl/acore/TestMapBufferRead02NEWT.java) + +## References +- [JogAmp Home](https://jogamp.org/) +- [JOGL Git Repo](https://jogamp.org/cgit/jogl.git/about/) +- [JOGL Home](https://jogamp.org/jogl/www/) +- [OpenGL Evolution & JOGL](https://jogamp.org/jogl/doc/Overview-OpenGL-Evolution-And-JOGL.html) +- [Mapping of OpenGL Profiles to Interfaces](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/overview-summary.html#overview_description) + - [OpenGL API Inclusion Criteria](https://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/overview-summary.html#GLAPIInclusionCriteria) + - [UML Diagram](https://jogamp.org/jogl/doc/uml/html/index-withframe.html) +- [How To Build](https://jogamp.org/jogl/doc/HowToBuild.html) |