com.jogamp.opengl.util

## Class GLPixelBuffer

- java.lang.Object
- - com.jogamp.opengl.util.GLPixelBuffer

- Direct Known Subclasses:
    AWTGLPixelBuffer

      public class GLPixelBuffer
      extends Object

  OpenGL pixel data buffer, allowing user to provide buffers via their `GLPixelBuffer.GLPixelBufferProvider` implementation.

  `GLPixelBuffer.GLPixelBufferProvider` produces a `GLPixelBuffer`.

  You may use `defaultProviderNoRowStride`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `GLPixelBuffer.DefaultGLPixelBufferProvider`
    `static class` | `GLPixelBuffer.GLPixelAttributes` Pixel attributes.
    `static interface` | `GLPixelBuffer.GLPixelBufferProvider` Allows user to interface with another toolkit to define `GLPixelBuffer.GLPixelAttributes` and memory buffer to produce `TextureData`.
    `static interface` | `GLPixelBuffer.SingletonGLPixelBufferProvider` Single `GLPixelBuffer` provider.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `boolean` | `allowRowStride` Allow `GL2ES3.GL_PACK_ROW_LENGTH`, or `GL2ES2.GL_UNPACK_ROW_LENGTH`.
    `Buffer` | `buffer` Buffer holding the pixel data.
    `int` | `bufferElemSize` Buffer element size in bytes.
    `int` | `byteSize` Byte size of the buffer.
    `static GLPixelBuffer.GLPixelBufferProvider` | `defaultProviderNoRowStride` Default `GLPixelBuffer.GLPixelBufferProvider` with `GLPixelBuffer.GLPixelBufferProvider.getAllowRowStride()` == `false`, utilizing best match for `GLPixelBuffer.GLPixelAttributes` and `allocating` a `ByteBuffer`.
    `static GLPixelBuffer.GLPixelBufferProvider` | `defaultProviderWithRowStride` Default `GLPixelBuffer.GLPixelBufferProvider` with `GLPixelBuffer.GLPixelBufferProvider.getAllowRowStride()` == `true`, utilizing best match for `GLPixelBuffer.GLPixelAttributes` and `allocating` a `ByteBuffer`.
    `int` | `depth` Depth in pixels.
    `int` | `height` Height in pixels, representing `buffer`'s `byteSize`.
    `boolean` | `pack` Data packing direction.
    `GLPixelBuffer.GLPixelAttributes` | `pixelAttributes` The `GLPixelBuffer.GLPixelAttributes`.
    `int` | `width` Width in pixels, representing `buffer`'s `byteSize`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GLPixelBuffer(GLPixelBuffer.GLPixelAttributes pixelAttributes, int width, int height, int depth, boolean pack, Buffer buffer, boolean allowRowStride)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `capacity()` Returns the byte capacity of the `buffer`.
    `Buffer` | `clear()` See `Buffer.clear()`.
    `void` | `dispose()` Dispose resources.
    `Buffer` | `flip()` See `Buffer.flip()`.
    `boolean` | `getAllowRowStride()` Allow `GL2ES3.GL_PACK_ROW_LENGTH`, or `GL2ES2.GL_UNPACK_ROW_LENGTH`.
    `boolean` | `isValid()` Is not `disposed` and has `byteSize` > 0.
    `int` | `limit()` Returns the byte limit of the `buffer`.
    `int` | `position()` Returns the byte position of the `buffer`.
    `Buffer` | `position(int bytePos)` Sets the byte position of the `buffer`.
    `boolean` | `requiresNewBuffer(GL gl, int newWidth, int newHeight, int newByteSize)` Returns true, if `invalid` or implementation requires a new buffer based on the new size due to pixel alignment or byte size, otherwise false.
    `Buffer` | `rewind()` See `Buffer.rewind()`.
    `String` | `toString()`
    `StringBuilder` | `toString(StringBuilder sb)`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### defaultProviderNoRowStride

          public static final GLPixelBuffer.GLPixelBufferProvider defaultProviderNoRowStride

      Default `GLPixelBuffer.GLPixelBufferProvider` with `GLPixelBuffer.GLPixelBufferProvider.getAllowRowStride()` == `false`, utilizing best match for `GLPixelBuffer.GLPixelAttributes` and `allocating` a `ByteBuffer`.

    - #### defaultProviderWithRowStride

          public static final GLPixelBuffer.GLPixelBufferProvider defaultProviderWithRowStride

      Default `GLPixelBuffer.GLPixelBufferProvider` with `GLPixelBuffer.GLPixelBufferProvider.getAllowRowStride()` == `true`, utilizing best match for `GLPixelBuffer.GLPixelAttributes` and `allocating` a `ByteBuffer`.

    - #### pixelAttributes

          public final GLPixelBuffer.GLPixelAttributes pixelAttributes

      The `GLPixelBuffer.GLPixelAttributes`.

    - #### width

          public final int width

      Width in pixels, representing `buffer`'s `byteSize`.

      May not represent actual image width as user may re-use buffer for different dimensions, see `requiresNewBuffer(GL, int, int, int)`.

    - #### height

          public final int height

      Height in pixels, representing `buffer`'s `byteSize`.

      May not represent actual image height as user may re-use buffer for different dimensions, see `requiresNewBuffer(GL, int, int, int)`.

    - #### depth

          public final int depth

      Depth in pixels.

    - #### pack

          public final boolean pack

      Data packing direction. If `true` for read mode GPU -> CPU, `false` for write mode CPU -> GPU.

    - #### byteSize

          public final int byteSize

      Byte size of the buffer. Actually the number of `Buffer.remaining()` bytes when passed in ctor.

    - #### buffer

          public final Buffer buffer

      Buffer holding the pixel data. If `rewind()`, it holds `byteSize` `Buffer.remaining()` bytes.

      By default the `Buffer` is a `ByteBuffer`, due to `DefProvider#allocate(GL, GLPixelAttributes, int, int, int, boolean, int)`. However, other `GLPixelBuffer.GLPixelBufferProvider` may utilize different `Buffer` types.

    - #### bufferElemSize

          public final int bufferElemSize

      Buffer element size in bytes.

    - #### allowRowStride

          public final boolean allowRowStride

      Allow `GL2ES3.GL_PACK_ROW_LENGTH`, or `GL2ES2.GL_UNPACK_ROW_LENGTH`. See `requiresNewBuffer(GL, int, int, int)`.

  - ### Constructor Detail

    - #### GLPixelBuffer

          public GLPixelBuffer(GLPixelBuffer.GLPixelAttributes pixelAttributes,
                       int width,
                       int height,
                       int depth,
                       boolean pack,
                       Buffer buffer,
                       boolean allowRowStride)

      Parameters:
        `pixelAttributes` - the desired `GLPixelBuffer.GLPixelAttributes`
        `width` - in pixels
        `height` - in pixels
        `depth` - in pixels
        `pack` - true for read mode GPU -> CPU, otherwise false for write mode CPU -> GPU
        `buffer` - the backing array
        `allowRowStride` - If `true`, allow row-stride, otherwise not. See `requiresNewBuffer(GL, int, int, int)`.

  - ### Method Detail

    - #### toString

          public StringBuilder toString(StringBuilder sb)

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### getAllowRowStride

          public final boolean getAllowRowStride()

      Allow `GL2ES3.GL_PACK_ROW_LENGTH`, or `GL2ES2.GL_UNPACK_ROW_LENGTH`.

    - #### isValid

          public boolean isValid()

      Is not `disposed` and has `byteSize` > 0.

    - #### rewind

          public Buffer rewind()

      See `Buffer.rewind()`.

    - #### position

          public int position()

      Returns the byte position of the `buffer`.

    - #### position

          public Buffer position(int bytePos)

      Sets the byte position of the `buffer`.

    - #### capacity

          public int capacity()

      Returns the byte capacity of the `buffer`.

    - #### limit

          public int limit()

      Returns the byte limit of the `buffer`.

    - #### flip

          public Buffer flip()

      See `Buffer.flip()`.

    - #### clear

          public Buffer clear()

      See `Buffer.clear()`.

    - #### requiresNewBuffer

          public boolean requiresNewBuffer(GL gl,
                                  int newWidth,
                                  int newHeight,
                                  int newByteSize)

      Returns true, if `invalid` or implementation requires a new buffer based on the new size due to pixel alignment or byte size, otherwise false.

      It is assumed that `pixelAttributes`, `depth` and `pack` stays the same!

      The minimum required byte size equals to `minByteSize`, if > 0, otherwise `GLBuffers.sizeof(..)` is being used to calculate it. This value is referred to newByteSize.

      If ``allowRowStride` = false`, method returns `true` if the newByteSize > currentByteSize or the `newWidth` != `currentWidth`.

      If ``allowRowStride` = true`, see `GLPixelBuffer.GLPixelBufferProvider.getAllowRowStride()`, method returns `true` only if the newByteSize > currentByteSize. Assuming user utilizes the row-stride when dealing w/ the data, i.e. `GL2ES3.GL_PACK_ROW_LENGTH`.

      Parameters:
        `gl` - the corresponding current GL context object
        `newWidth` - new width in pixels
        `newHeight` - new height in pixels
        `newByteSize` - if > 0, the pre-calculated minimum byte-size for the resulting buffer, otherwise ignore.
      See Also:
        `GLPixelBufferProvider#allocate(GL, GLPixelAttributes, int, int, int, boolean, int)`

    - #### dispose

          public void dispose()

      Dispose resources. See `isValid()`.

Copyright 2010 JogAmp Community.