org.lwjgl.system.CustomBuffer Maven / Gradle / Ivy
/*
* Copyright LWJGL. All rights reserved.
* License terms: https://www.lwjgl.org/license
*/
package org.lwjgl.system;
import java.nio.*;
import static org.lwjgl.system.MemoryUtil.*;
/** Base class of custom buffers with an API that mirrors {@code java.nio} for convenience. */
public abstract class CustomBuffer> implements Pointer {
protected long address;
protected ByteBuffer container;
protected int
mark,
position,
limit,
capacity;
protected CustomBuffer(long address, ByteBuffer container, int mark, int position, int limit, int capacity) {
this.address = address;
this.container = container;
this.mark = mark;
this.position = position;
this.limit = limit;
this.capacity = capacity;
}
/** Returns the buffer's base address. [INTERNAL USE ONLY] */
public long address0() {
return address;
}
/** Returns the memory address at the current buffer position. */
@Override
public long address() { return address(position()); }
/** Returns the memory address at the specified buffer position. */
public long address(int position) {
return address + position * sizeof();
}
/**
* Frees the buffer allocation.
*
* This method should not be used if the memory backing this buffer is not owned by the buffer.
*/
public void free() {
nmemFree(address0());
}
/**
* Returns this buffer's capacity.
*
* @return the capacity of this buffer
*/
public int capacity() {
return capacity;
}
/**
* Returns this buffer's position.
*
* @return the position of this buffer
*/
public int position() {
return position;
}
/**
* Sets this buffer's position. If the mark is defined and larger than the new position then it is discarded.
*
* @param newPosition the new position value; must be non-negative and no larger than the current limit
*
* @return This buffer
*
* @throws IllegalArgumentException If the preconditions on newPosition do not hold
*/
public SELF position(int newPosition) {
if ( (newPosition > limit) || (newPosition < 0) )
throw new IllegalArgumentException();
position = newPosition;
if ( mark > position ) mark = -1;
return self();
}
/**
* Returns this buffer's limit.
*
* @return the limit of this buffer
*/
public int limit() {
return limit;
}
/**
* Sets this buffer's limit. If the position is larger than the new limit then it is set to the new limit. If the mark is defined and larger than the new
* limit then it is discarded.
*
* @param newLimit the new limit value; must be non-negative and no larger than this buffer's capacity
*
* @return This buffer
*
* @throws IllegalArgumentException If the preconditions on newLimit do not hold
*/
public SELF limit(int newLimit) {
if ( (newLimit > capacity) || (newLimit < 0) )
throw new IllegalArgumentException();
limit = newLimit;
if ( position > limit ) position = limit;
if ( mark > limit ) mark = -1;
return self();
}
/**
* Sets this buffer's mark at its position.
*
* @return This buffer
*/
public SELF mark() {
mark = position;
return self();
}
/**
* Resets this buffer's position to the previously-marked position.
*
* Invoking this method neither changes nor discards the mark's value.
*
* @return This buffer
*
* @throws java.nio.InvalidMarkException If the mark has not been set
*/
public SELF reset() {
int m = mark;
if ( m < 0 )
throw new InvalidMarkException();
position = m;
return self();
}
/**
* Clears this buffer. The position is set to zero, the limit is set to the capacity, and the mark is discarded.
*
* Invoke this method before using a sequence of channel-read or put operations to fill this buffer. For example:
*
*
* buf.clear(); // Prepare buffer for reading
* in.read(buf); // Read data
*
* This method does not actually erase the data in the buffer, but it is named as if it did because it will most often be used in situations in which
* that might as well be the case.
*
* @return This buffer
*/
public SELF clear() {
position = 0;
limit = capacity;
mark = -1;
return self();
}
/**
* Flips this buffer. The limit is set to the current position and then the position is set to zero. If the mark is defined then it is discarded.
*
* After a sequence of channel-read or put operations, invoke this method to prepare for a sequence of channel-write or relative get
* operations. For example:
*
*
* buf.put(magic); // Prepend header
* in.read(buf); // Read data into rest of buffer
* buf.flip(); // Flip buffer
* out.write(buf); // Write header + data to channel
*
* This method is often used in conjunction with the {@link #compact} method when transferring data from one place to another.
*
* @return This buffer
*/
public SELF flip() {
limit = position;
position = 0;
mark = -1;
return self();
}
/**
* Rewinds this buffer. The position is set to zero and the mark is discarded.
*
* Invoke this method before a sequence of channel-write or get operations, assuming that the limit has already been set appropriately. For
* example:
*
*
* out.write(buf); // Write remaining data
* buf.rewind(); // Rewind buffer
* buf.get(array); // Copy data into array
*
* @return This buffer
*/
public SELF rewind() {
position = 0;
mark = -1;
return self();
}
/**
* Returns the number of elements between the current position and the limit.
*
* @return the number of elements remaining in this buffer
*/
public int remaining() {
return limit - position;
}
/**
* Tells whether there are any elements between the current position and the limit.
*
* @return true if, and only if, there is at least one element remaining in this buffer
*/
public boolean hasRemaining() {
return position < limit;
}
/**
* Creates a new buffer whose content is a shared subsequence of this buffer's content.
*
* The content of the new buffer will start at this buffer's current position. Changes to this buffer's content will be visible in the new buffer, and
* vice versa; the two buffers' position, limit, and mark values will be independent.
*
* The new buffer's position will be zero, its capacity and its limit will be the number of elements remaining in this buffer, and its mark will be
* undefined. The new buffer will be read-only if, and only if, this buffer is read-only.
*
* @return the new buffer
*/
public SELF slice() {
return newBufferInstance(address(), container, -1, 0, this.remaining(), this.remaining());
}
/**
* Returns a slice of this buffer between {@code (buffer.position() + offset)} and {@code (buffer.position() + offset + capacity)}.
*
* The position and limit of this buffer are preserved after a call to this method.
*
* @param offset the slice offset, it must be ≤ {@code this.remaining()}
* @param capacity the slice length, it must be ≤ {@code this.capacity() - (this.position() + offset)}
*
* @return the sliced buffer
*/
public SELF slice(int offset, int capacity) {
if ( offset < 0 || limit < position + offset )
throw new IllegalArgumentException();
if ( capacity < 0 || this.capacity < position + offset + capacity )
throw new IllegalArgumentException();
return newBufferInstance(address() + offset * sizeof(), container, -1, 0, capacity, capacity);
}
/**
* Creates a new buffer that shares this buffer's content.
*
* The content of the new buffer will be that of this buffer. Changes to this buffer's content will be visible in the new buffer, and vice versa; the
* two buffers' position, limit, and mark values will be independent.
*
*
The new buffer's capacity, limit and position will be identical to those of this buffer.
*
* @return the new buffer
*/
public SELF duplicate() {
return newBufferInstance(address, container, mark, position, limit, capacity);
}
// -- Bulk get operations --
/**
* Relative bulk put method (optional operation).
*
* This method transfers the elements remaining in the specified source buffer into this buffer. If there are more elements remaining in the source
* buffer than in this buffer, that is, if src.remaining() > remaining(), then no elements are transferred and a
* {@link java.nio.BufferOverflowException} is thrown.
*
*
Otherwise, this method copies n = src.remaining() elements from the specified buffer into this buffer, starting at each
* buffer's current position. The positions of both buffers are then incremented by n.
*
* In other words, an invocation of this method of the form dst.put(src) has exactly the same effect as the loop
*
*
* while (src.hasRemaining())
* dst.put(src.get());
*
* except that it first checks that there is sufficient space in this buffer and it is potentially much more efficient.
*
* @param src the source buffer from which elements are to be read; must not be this buffer
*
* @return This buffer
*
* @throws java.nio.BufferOverflowException If there is insufficient space in this buffer for the remaining elements in the source buffer
* @throws IllegalArgumentException If the source buffer is this buffer
* @throws java.nio.ReadOnlyBufferException If this buffer is read-only
*/
public SELF put(SELF src) {
if ( src == this )
throw new IllegalArgumentException();
int n = src.remaining();
if ( n > remaining() )
throw new BufferOverflowException();
memCopy(src.address(), this.address(), n * sizeof());
position += n;
return self();
}
/**
* Compacts this buffer (optional operation).
*
* The elements between the buffer's current position and its limit, if any, are copied to the beginning of the buffer. That is, the element at index
* p = position() is copied to index zero, the element at index p + 1 is copied to index one, and so forth until
* the element at index limit() - 1 is copied to index n = limit() - 1 -
* p.
* The buffer's position is then set to n+1 and its limit is set to its capacity. The mark, if defined, is discarded.
*
*
The buffer's position is set to the number of elements copied, rather than to zero, so that an invocation of this method can be followed
* immediately by an invocation of another relative put method.
*
* @return This buffer
*
* @throws java.nio.ReadOnlyBufferException If this buffer is read-only
*/
public SELF compact() {
memCopy(address(), address, remaining() * sizeof());
position(remaining());
limit(capacity());
mark = -1;
return self();
}
/**
* Returns a string summarizing the state of this buffer.
*
* @return A summary string
*/
public String toString() {
return getClass().getName() + "[pos=" + position() + " lim=" + limit() + " cap=" + capacity() + "]";
}
// -----------------------------
protected abstract SELF self();
protected abstract int sizeof();
protected abstract SELF newBufferInstance(long address, ByteBuffer container, int mark, int position, int limit, int capacity);
protected int nextGetIndex() {
if ( position >= limit )
throw new BufferUnderflowException();
return position++;
}
protected int nextPutIndex() {
if ( position >= limit )
throw new BufferOverflowException();
return position++;
}
protected int checkIndex(int index) {
if ( index < 0 || limit < index )
throw new IndexOutOfBoundsException();
return index;
}
}