From c4b0494f729d9fb1ecf69e399c3a8d683f772d05 Mon Sep 17 00:00:00 2001
From: Kenneth Russel <kbrussel@alum.mit.edu>
Date: Sun, 22 Jan 2006 16:50:38 +0000
Subject: Fixed Issue 179: Add documentation on importance of byte ordering

Added text to the spec overview regarding setting byte order of
newly-allocated ByteBuffers to native order.


git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/trunk@558 232f8b59-042b-4e1e-8c03-345bb8c30851
---
 make/spec-overview.html | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

(limited to 'make')

diff --git a/make/spec-overview.html b/make/spec-overview.html
index 36b92e2cc..fdeb972c2 100644
--- a/make/spec-overview.html
+++ b/make/spec-overview.html
@@ -135,6 +135,20 @@ all Buffer types.<br>
 all non-direct Buffers.  Direct and non-direct buffers should never be mixed
 within an API call by an application.<br>
  
+<h4>Byte ordering of Buffers</h4>
+ When allocating a New I/O Buffer (in particular, a direct ByteBuffer)
+to be passed to the APIs in these packages, it is essential to set the
+<em>byte ordering</em> of the newly-allocated ByteBuffer to the
+<em>native</em> byte ordering of the platform:
+e.g. <code>ByteBuffer.allocateDirect(...).order(ByteOrder.nativeOrder());</code>.
+The byte order of the ByteBuffer indicates how multi-byte values such
+as int and float are stored in the Buffer either using methods like
+putInt and putFloat or views such as IntBuffer or FloatBuffer. The
+Java bindings perform no conversion or byte swapping on the outgoing
+data to OpenGL, and the native OpenGL implementation expects data in
+the host CPU's byte order, so it is essential to always match the byte
+order of the underlying platform when filling Buffers with data. <br>
+
 <h4>Auto-slicing of Buffers</h4>
  When a Buffer object is passed to an OpenGL function binding, the actual
 pointer argument that is passed down to the OpenGL C implementation is equal
-- 
cgit v1.2.3