Package org.lwjgl.system

Class MemoryStack

    • Method Detail

      • create

        public static MemoryStack create()
        Creates a new MemoryStack with the default size.

        In the initial state, there is no active stack frame. The push() method must be used before any allocations.

      • create

        public static MemoryStack create​(int capacity)
        Creates a new MemoryStack with the specified size.

        In the initial state, there is no active stack frame. The push() method must be used before any allocations.

        Parameters:
        capacity - the maximum number of bytes that may be allocated on the stack

      • create

        public static MemoryStack create​(java.nio.ByteBuffer buffer)
        Creates a new MemoryStack backed by the specified memory buffer.

        In the initial state, there is no active stack frame. The push() method must be used before any allocations.

        Parameters:
        buffer - the backing memory buffer

      • ncreate

        public static MemoryStack ncreate​(long address,
                                  int size)
        Creates a new MemoryStack backed by the specified memory region.

        In the initial state, there is no active stack frame. The push() method must be used before any allocations.

        Parameters:
        address - the backing memory address
        size - the backing memory size

      • push

        public MemoryStack push()
        Stores the current stack pointer and pushes a new frame to the stack.

        This method should be called when entering a method, before doing any stack allocations. When exiting a method, call the pop() method to restore the previous stack frame.

        Pairs of push/pop calls may be nested. Care must be taken to:

        • match every push with a pop
        • not call pop before push has been called at least once
        • not nest push calls to more than the maximum supported depth
        Returns:
        this stack

      • pop

        public MemoryStack pop()
        Pops the current stack frame and moves the stack pointer to the end of the previous stack frame.
        Returns:
        this stack

      • close

        public void close()
        Calls pop() on this MemoryStack.

        This method should not be used directly. It is called automatically when the MemoryStack is used as a resource in a try-with-resources statement.

        Specified by:
        close in interface java.lang.AutoCloseable

      • getAddress

        public long getAddress()
        Returns the address of the backing off-heap memory.

        The stack grows "downwards", so the bottom of the stack is at address + size, while the top is at address.

      • getSize

        public int getSize()
        Returns the size of the backing off-heap memory.

        This is the maximum number of bytes that may be allocated on the stack.

      • getFrameIndex

        public int getFrameIndex()
        Returns the current frame index.

        This is the current number of nested push() calls.

      • getPointerAddress

        public long getPointerAddress()
        Returns the memory address at the current stack pointer.

      • getPointer

        public int getPointer()
        Returns the current stack pointer.

        The stack grows "downwards", so when the stack is empty pointer is equal to size. On every allocation pointer is reduced by the allocated size (after alignment) and address + pointer points to the first byte of the last allocation.

        Effectively, this methods returns how many more bytes may be allocated on the stack.

      • setPointer

        public void setPointer​(int pointer)
        Sets the current stack pointer.

        This method directly manipulates the stack pointer. Using it irresponsibly may break the internal state of the stack. It should only be used in rare cases or in auto-generated code.

      • nmalloc

        public long nmalloc​(int size)
        Calls nmalloc(int, int) with alignment equal to 1.
        Parameters:
        size - the allocation size
        Returns:
        the memory address on the stack for the requested allocation

      • nmalloc

        public long nmalloc​(int alignment,
                    int size)
        Allocates a block of size bytes of memory on the stack. The content of the newly allocated block of memory is not initialized, remaining with indeterminate values.
        Parameters:
        alignment - the required alignment
        size - the allocation size
        Returns:
        the memory address on the stack for the requested allocation

      • ncalloc

        public long ncalloc​(int alignment,
                    int num,
                    int size)
        Allocates a block of memory on the stack for an array of num elements, each of them size bytes long, and initializes all its bits to zero.
        Parameters:
        alignment - the required element alignment
        num - num the number of elements to allocate
        size - the size of each element
        Returns:
        the memory address on the stack for the requested allocation

      • malloc

        public java.nio.ByteBuffer malloc​(int alignment,
                                  int size)
        Allocates an aligned ByteBuffer on the stack.
        Parameters:
        alignment - the required buffer alignment
        size - the number of elements in the buffer
        Returns:
        the allocated buffer

      • calloc

        public java.nio.ByteBuffer calloc​(int alignment,
                                  int size)
        Calloc version of malloc(int, int).

      • malloc

        public java.nio.ByteBuffer malloc​(int size)
        Allocates a ByteBuffer on the stack.
        Parameters:
        size - the number of elements in the buffer
        Returns:
        the allocated buffer

      • calloc

        public java.nio.ByteBuffer calloc​(int size)
        Calloc version of malloc(int).

      • bytes

        public java.nio.ByteBuffer bytes​(byte x)
        Single value version of malloc(int, int).

      • bytes

        public java.nio.ByteBuffer bytes​(byte x,
                                 byte y)
        Two value version of malloc(int, int).

      • bytes

        public java.nio.ByteBuffer bytes​(byte x,
                                 byte y,
                                 byte z)
        Three value version of malloc(int, int).

      • bytes

        public java.nio.ByteBuffer bytes​(byte x,
                                 byte y,
                                 byte z,
                                 byte w)
        Four value version of malloc(int, int).

      • bytes

        public java.nio.ByteBuffer bytes​(byte... values)
        Vararg version of malloc(int, int).

      • mallocShort

        public java.nio.ShortBuffer mallocShort​(int size)
        Short version of malloc(int).

      • callocShort

        public java.nio.ShortBuffer callocShort​(int size)
        Short version of calloc(int).

      • shorts

        public java.nio.ShortBuffer shorts​(short x)
        Single value version of mallocShort(int).

      • shorts

        public java.nio.ShortBuffer shorts​(short x,
                                   short y)
        Two value version of mallocShort(int).

      • shorts

        public java.nio.ShortBuffer shorts​(short x,
                                   short y,
                                   short z)
        Three value version of mallocShort(int).

      • shorts

        public java.nio.ShortBuffer shorts​(short x,
                                   short y,
                                   short z,
                                   short w)
        Four value version of mallocShort(int).

      • shorts

        public java.nio.ShortBuffer shorts​(short... values)
        Vararg version of mallocShort(int).

      • mallocInt

        public java.nio.IntBuffer mallocInt​(int size)
        Int version of malloc(int).

      • callocInt

        public java.nio.IntBuffer callocInt​(int size)
        Int version of calloc(int).

      • ints

        public java.nio.IntBuffer ints​(int x)
        Single value version of mallocInt(int).

      • ints

        public java.nio.IntBuffer ints​(int x,
                               int y)
        Two value version of mallocInt(int).

      • ints

        public java.nio.IntBuffer ints​(int x,
                               int y,
                               int z)
        Three value version of mallocInt(int).

      • ints

        public java.nio.IntBuffer ints​(int x,
                               int y,
                               int z,
                               int w)
        Four value version of mallocInt(int).

      • ints

        public java.nio.IntBuffer ints​(int... values)
        Vararg version of mallocInt(int).

      • mallocLong

        public java.nio.LongBuffer mallocLong​(int size)
        Long version of malloc(int).

      • callocLong

        public java.nio.LongBuffer callocLong​(int size)
        Long version of calloc(int).

      • longs

        public java.nio.LongBuffer longs​(long x)
        Single value version of mallocLong(int).

      • longs

        public java.nio.LongBuffer longs​(long x,
                                 long y)
        Two value version of mallocLong(int).

      • longs

        public java.nio.LongBuffer longs​(long x,
                                 long y,
                                 long z)
        Three value version of mallocLong(int).

      • longs

        public java.nio.LongBuffer longs​(long x,
                                 long y,
                                 long z,
                                 long w)
        Four value version of mallocLong(int).

      • longs

        public java.nio.LongBuffer longs​(long... more)
        Vararg version of mallocLong(int).

      • mallocFloat

        public java.nio.FloatBuffer mallocFloat​(int size)
        Float version of malloc(int).

      • callocFloat

        public java.nio.FloatBuffer callocFloat​(int size)
        Float version of calloc(int).

      • floats

        public java.nio.FloatBuffer floats​(float x)
        Single value version of mallocFloat(int).

      • floats

        public java.nio.FloatBuffer floats​(float x,
                                   float y)
        Two value version of mallocFloat(int).

      • floats

        public java.nio.FloatBuffer floats​(float x,
                                   float y,
                                   float z)
        Three value version of mallocFloat(int).

      • floats

        public java.nio.FloatBuffer floats​(float x,
                                   float y,
                                   float z,
                                   float w)
        Four value version of mallocFloat(int).

      • floats

        public java.nio.FloatBuffer floats​(float... values)
        Vararg version of mallocFloat(int).

      • mallocDouble

        public java.nio.DoubleBuffer mallocDouble​(int size)
        Double version of malloc(int).

      • callocDouble

        public java.nio.DoubleBuffer callocDouble​(int size)
        Double version of calloc(int).

      • doubles

        public java.nio.DoubleBuffer doubles​(double x)
        Single value version of mallocDouble(int).

      • doubles

        public java.nio.DoubleBuffer doubles​(double x,
                                     double y)
        Two value version of mallocDouble(int).

      • doubles

        public java.nio.DoubleBuffer doubles​(double x,
                                     double y,
                                     double z)
        Three value version of mallocDouble(int).

      • doubles

        public java.nio.DoubleBuffer doubles​(double x,
                                     double y,
                                     double z,
                                     double w)
        Four value version of mallocDouble(int).

      • doubles

        public java.nio.DoubleBuffer doubles​(double... values)
        Vararg version of mallocDouble(int).

      • pointers

        public PointerBuffer pointers​(java.nio.Buffer x,
                              java.nio.Buffer y,
                              java.nio.Buffer z,
                              java.nio.Buffer w)
        Four value version of mallocPointer(int).

      • ASCII

        public java.nio.ByteBuffer ASCII​(java.lang.CharSequence text)
        Encodes the specified text on the stack using ASCII encoding and returns a ByteBuffer that points to the encoded text, including a null-terminator.
        Parameters:
        text - the text to encode

      • ASCII

        public java.nio.ByteBuffer ASCII​(java.lang.CharSequence text,
                                 boolean nullTerminated)
        Encodes the specified text on the stack using ASCII encoding and returns a ByteBuffer that points to the encoded text.
        Parameters:
        text - the text to encode
        nullTerminated - if true, a null-terminator is included at the end of the encoded text

      • nASCII

        public int nASCII​(java.lang.CharSequence text,
                  boolean nullTerminated)
        Encodes the specified text on the stack using ASCII encoding and returns the encoded text length, in bytes.

        Use getPointerAddress() immediately after this method to get the encoded text address.

        Parameters:
        text - the text to encode
        nullTerminated - if true, a null-terminator is included at the end of the encoded text

      • ASCIISafe

        @Nullable
public java.nio.ByteBuffer ASCIISafe​(@Nullable
                                     java.lang.CharSequence text)
        Like ASCII, but returns null if text is null.

      • ASCIISafe

        @Nullable
public java.nio.ByteBuffer ASCIISafe​(@Nullable
                                     java.lang.CharSequence text,
                                     boolean nullTerminated)
        Like ASCII, but returns null if text is null.

      • nASCIISafe

        public int nASCIISafe​(@Nullable
                      java.lang.CharSequence text,
                      boolean nullTerminated)
        Like nASCII, but returns 0 if text is null.

      • UTF8

        public java.nio.ByteBuffer UTF8​(java.lang.CharSequence text)
        Encodes the specified text on the stack using UTF8 encoding and returns a ByteBuffer that points to the encoded text, including a null-terminator.
        Parameters:
        text - the text to encode

      • UTF8

        public java.nio.ByteBuffer UTF8​(java.lang.CharSequence text,
                                boolean nullTerminated)
        Encodes the specified text on the stack using UTF8 encoding and returns a ByteBuffer that points to the encoded text.
        Parameters:
        text - the text to encode
        nullTerminated - if true, a null-terminator is included at the end of the encoded text

      • nUTF8

        public int nUTF8​(java.lang.CharSequence text,
                 boolean nullTerminated)
        Encodes the specified text on the stack using UTF8 encoding and returns the encoded text length, in bytes.

        Use getPointerAddress() immediately after this method to get the encoded text address.

        Parameters:
        text - the text to encode
        nullTerminated - if true, a null-terminator is included at the end of the encoded text

      • UTF8Safe

        @Nullable
public java.nio.ByteBuffer UTF8Safe​(@Nullable
                                    java.lang.CharSequence text)
        Like UTF8, but returns null if text is null.

      • UTF8Safe

        @Nullable
public java.nio.ByteBuffer UTF8Safe​(@Nullable
                                    java.lang.CharSequence text,
                                    boolean nullTerminated)
        Like UTF8, but returns null if text is null.

      • nUTF8Safe

        public int nUTF8Safe​(@Nullable
                     java.lang.CharSequence text,
                     boolean nullTerminated)
        Like nUTF8, but returns 0 if text is null.

      • UTF16

        public java.nio.ByteBuffer UTF16​(java.lang.CharSequence text)
        Encodes the specified text on the stack using UTF16 encoding and returns a ByteBuffer that points to the encoded text, including a null-terminator.
        Parameters:
        text - the text to encode

      • UTF16

        public java.nio.ByteBuffer UTF16​(java.lang.CharSequence text,
                                 boolean nullTerminated)
        Encodes the specified text on the stack using UTF16 encoding and returns a ByteBuffer that points to the encoded text.
        Parameters:
        text - the text to encode
        nullTerminated - if true, a null-terminator is included at the end of the encoded text

      • nUTF16

        public int nUTF16​(java.lang.CharSequence text,
                  boolean nullTerminated)
        Encodes the specified text on the stack using UTF16 encoding and returns the encoded text length, in bytes.

        Use getPointerAddress() immediately after this method to get the encoded text address.

        Parameters:
        text - the text to encode
        nullTerminated - if true, a null-terminator is included at the end of the encoded text

      • UTF16Safe

        @Nullable
public java.nio.ByteBuffer UTF16Safe​(@Nullable
                                     java.lang.CharSequence text)
        Like UTF16, but returns null if text is null.

      • UTF16Safe

        @Nullable
public java.nio.ByteBuffer UTF16Safe​(@Nullable
                                     java.lang.CharSequence text,
                                     boolean nullTerminated)
        Like UTF16, but returns null if text is null.

      • nUTF16Safe

        public int nUTF16Safe​(@Nullable
                      java.lang.CharSequence text,
                      boolean nullTerminated)
        Like nUTF16, but returns 0 if text is null.

      • stackGet

        public static MemoryStack stackGet()
        Returns the stack of the current thread.

      • stackPush

        public static MemoryStack stackPush()
        Calls push() on the stack of the current thread.
        Returns:
        the stack of the current thread.

      • stackPop

        public static MemoryStack stackPop()
        Calls pop() on the stack of the current thread.
        Returns:
        the stack of the current thread.

      • nstackMalloc

        public static long nstackMalloc​(int size)
        Thread-local version of nmalloc(int).

      • nstackMalloc

        public static long nstackMalloc​(int alignment,
                                int size)
        Thread-local version of nmalloc(int, int).

      • nstackCalloc

        public static long nstackCalloc​(int alignment,
                                int num,
                                int size)
        Thread-local version of ncalloc(int, int, int).

      • stackMalloc

        public static java.nio.ByteBuffer stackMalloc​(int size)
        Thread-local version of malloc(int, int).

      • stackCalloc

        public static java.nio.ByteBuffer stackCalloc​(int size)
        Thread-local version of calloc(int, int).

      • stackBytes

        public static java.nio.ByteBuffer stackBytes​(byte x)
        Thread-local version of bytes(byte).

      • stackBytes

        public static java.nio.ByteBuffer stackBytes​(byte x,
                                             byte y)
        Thread-local version of bytes(byte, byte).

      • stackBytes

        public static java.nio.ByteBuffer stackBytes​(byte x,
                                             byte y,
                                             byte z)
        Thread-local version of bytes(byte, byte, byte).

      • stackBytes

        public static java.nio.ByteBuffer stackBytes​(byte x,
                                             byte y,
                                             byte z,
                                             byte w)
        Thread-local version of bytes(byte, byte, byte, byte).

      • stackBytes

        public static java.nio.ByteBuffer stackBytes​(byte... values)
        Thread-local version of bytes(byte...).

      • stackMallocShort

        public static java.nio.ShortBuffer stackMallocShort​(int size)
        Thread-local version of mallocShort(int).

      • stackCallocShort

        public static java.nio.ShortBuffer stackCallocShort​(int size)
        Thread-local version of callocShort(int).

      • stackShorts

        public static java.nio.ShortBuffer stackShorts​(short x)
        Thread-local version of shorts(short).

      • stackShorts

        public static java.nio.ShortBuffer stackShorts​(short x,
                                               short y)
        Thread-local version of shorts(short, short).

      • stackShorts

        public static java.nio.ShortBuffer stackShorts​(short x,
                                               short y,
                                               short z)
        Thread-local version of shorts(short, short, short).

      • stackShorts

        public static java.nio.ShortBuffer stackShorts​(short... values)
        Thread-local version of shorts(short...).

      • stackMallocInt

        public static java.nio.IntBuffer stackMallocInt​(int size)
        Thread-local version of mallocInt(int).

      • stackCallocInt

        public static java.nio.IntBuffer stackCallocInt​(int size)
        Thread-local version of callocInt(int).

      • stackInts

        public static java.nio.IntBuffer stackInts​(int x)
        Thread-local version of ints(int).

      • stackInts

        public static java.nio.IntBuffer stackInts​(int x,
                                           int y)
        Thread-local version of ints(int, int).

      • stackInts

        public static java.nio.IntBuffer stackInts​(int x,
                                           int y,
                                           int z)
        Thread-local version of ints(int, int, int).

      • stackInts

        public static java.nio.IntBuffer stackInts​(int x,
                                           int y,
                                           int z,
                                           int w)
        Thread-local version of ints(int, int, int, int).

      • stackInts

        public static java.nio.IntBuffer stackInts​(int... values)
        Thread-local version of ints(int...).

      • stackMallocLong

        public static java.nio.LongBuffer stackMallocLong​(int size)
        Thread-local version of mallocLong(int).

      • stackCallocLong

        public static java.nio.LongBuffer stackCallocLong​(int size)
        Thread-local version of callocLong(int).

      • stackLongs

        public static java.nio.LongBuffer stackLongs​(long x)
        Thread-local version of longs(long).

      • stackLongs

        public static java.nio.LongBuffer stackLongs​(long x,
                                             long y)
        Thread-local version of longs(long, long).

      • stackLongs

        public static java.nio.LongBuffer stackLongs​(long x,
                                             long y,
                                             long z)
        Thread-local version of longs(long, long, long).

      • stackLongs

        public static java.nio.LongBuffer stackLongs​(long x,
                                             long y,
                                             long z,
                                             long w)
        Thread-local version of longs(long, long, long, long).

      • stackLongs

        public static java.nio.LongBuffer stackLongs​(long... values)
        Thread-local version of longs(long...).

      • stackMallocFloat

        public static java.nio.FloatBuffer stackMallocFloat​(int size)
        Thread-local version of mallocFloat(int).

      • stackCallocFloat

        public static java.nio.FloatBuffer stackCallocFloat​(int size)
        Thread-local version of callocFloat(int).

      • stackFloats

        public static java.nio.FloatBuffer stackFloats​(float x)
        Thread-local version of floats(float).

      • stackFloats

        public static java.nio.FloatBuffer stackFloats​(float x,
                                               float y)
        Thread-local version of floats(float, float).

      • stackFloats

        public static java.nio.FloatBuffer stackFloats​(float x,
                                               float y,
                                               float z)
        Thread-local version of floats(float, float, float).

      • stackFloats

        public static java.nio.FloatBuffer stackFloats​(float... values)
        Thread-local version of floats(float...).

      • stackMallocDouble

        public static java.nio.DoubleBuffer stackMallocDouble​(int size)
        Thread-local version of mallocDouble(int).

      • stackCallocDouble

        public static java.nio.DoubleBuffer stackCallocDouble​(int size)
        Thread-local version of callocDouble(int).

      • stackDoubles

        public static java.nio.DoubleBuffer stackDoubles​(double x)
        Thread-local version of doubles(double).

      • stackDoubles

        public static java.nio.DoubleBuffer stackDoubles​(double x,
                                                 double y)
        Thread-local version of doubles(double, double).

      • stackDoubles

        public static java.nio.DoubleBuffer stackDoubles​(double x,
                                                 double y,
                                                 double z)
        Thread-local version of doubles(double, double, double).

      • stackDoubles

        public static java.nio.DoubleBuffer stackDoubles​(double... values)
        Thread-local version of doubles(double...).

      • stackASCII

        public static java.nio.ByteBuffer stackASCII​(java.lang.CharSequence text)
        Thread-local version of ASCII(CharSequence).

      • stackASCII

        public static java.nio.ByteBuffer stackASCII​(java.lang.CharSequence text,
                                             boolean nullTerminated)
        Thread-local version of ASCII(CharSequence, boolean).

      • stackUTF8

        public static java.nio.ByteBuffer stackUTF8​(java.lang.CharSequence text)
        Thread-local version of UTF8(CharSequence).

      • stackUTF8

        public static java.nio.ByteBuffer stackUTF8​(java.lang.CharSequence text,
                                            boolean nullTerminated)
        Thread-local version of UTF8(CharSequence, boolean).

      • stackUTF16

        public static java.nio.ByteBuffer stackUTF16​(java.lang.CharSequence text)
        Thread-local version of UTF16(CharSequence).

      • stackUTF16

        public static java.nio.ByteBuffer stackUTF16​(java.lang.CharSequence text,
                                             boolean nullTerminated)
        Thread-local version of UTF16(CharSequence, boolean).

      • stackASCIISafe

        @Nullable
public static java.nio.ByteBuffer stackASCIISafe​(@Nullable
                                                 java.lang.CharSequence text)
        Thread-local version of ASCII(CharSequence).

      • stackASCIISafe

        @Nullable
public static java.nio.ByteBuffer stackASCIISafe​(@Nullable
                                                 java.lang.CharSequence text,
                                                 boolean nullTerminated)
        Thread-local version of ASCII(CharSequence, boolean).

      • stackUTF8Safe

        @Nullable
public static java.nio.ByteBuffer stackUTF8Safe​(@Nullable
                                                java.lang.CharSequence text)
        Thread-local version of UTF8(CharSequence).

      • stackUTF8Safe

        @Nullable
public static java.nio.ByteBuffer stackUTF8Safe​(@Nullable
                                                java.lang.CharSequence text,
                                                boolean nullTerminated)
        Thread-local version of UTF8(CharSequence, boolean).

      • stackUTF16Safe

        @Nullable
public static java.nio.ByteBuffer stackUTF16Safe​(@Nullable
                                                 java.lang.CharSequence text)
        Thread-local version of UTF16(CharSequence).

      • stackUTF16Safe

        @Nullable
public static java.nio.ByteBuffer stackUTF16Safe​(@Nullable
                                                 java.lang.CharSequence text,
                                                 boolean nullTerminated)
        Thread-local version of UTF16(CharSequence, boolean).