Update README.md, index.html (Graph/GraphUI, references) and add OpenGL_API_Divergence.md

author: Sven Gothel <[email protected]> 2023-08-07 04:11:58 +0200
committer: Sven Gothel <[email protected]> 2023-08-07 04:11:58 +0200
commit: 430b8a061b061ceb9c03deb84380335612f71737 (patch)
tree: 9e306843b51e6f3022a319dde6bf9c7f9d6ad2de /doc
parent: bcc4b5de41dcfca5eac19111506b996d3531d908 (diff)
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 &amp; 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)
author	Sven Gothel <[email protected]>	2023-08-07 04:11:58 +0200
committer	Sven Gothel <[email protected]>	2023-08-07 04:11:58 +0200
commit	430b8a061b061ceb9c03deb84380335612f71737 (patch)
tree	9e306843b51e6f3022a319dde6bf9c7f9d6ad2de /doc
parent	bcc4b5de41dcfca5eac19111506b996d3531d908 (diff)