org.lwjgl.opengl

Class ARBInvalidateSubdata

java.lang.Object

org.lwjgl.opengl.ARBInvalidateSubdata

public class ARBInvalidateSubdata
extends java.lang.Object

Native bindings to the ARB_invalidate_subdata extension.

This extension adds a mechanism for an application to tell the GL that the previous contents of a subregion of an image or a range of a buffer may be invalidated.

GL implementations often include several memory spaces, each with distinct performance characteristics, and the implementations transparently move allocations between memory spaces. With this extension, an application can tell the GL that the contents of a texture or buffer are no longer needed, and the implementation can avoid transferring the data unnecessarily.

Examples of when this may be useful include:

1. invalidating a multisample texture after resolving it into a non-multisample texture.
2. invalidating depth/stencil buffers after using them to generate a color buffer.
3. invalidating a subregion of a framebuffer rather than clearing it before rendering to it, when the whole subregion will be overwritten.
4. invalidating dynamically generated data (e.g. textures written by FBO rendering or CopyTexSubImage, buffers written by transform feedback, etc.) after it is no longer needed but before the end of the frame.

It is expected that the situations in which the GL will take advantage of this knowledge and achieve increased performance as a result of its use will be implementation-dependent. The first three examples may show benefit on tiled renderers where some data won't need to be copied into or out of on-chip memory. The fourth example may show a benefit in multi-GPU systems where some data won't need to be copied between GPUs.

This extension is a superset of the EXT_discard_framebuffer extension with the following additions:

• The parameters to InvalidateFramebufferEXT are extended for MRT support and Desktop-GL-only buffer enums.
• New functions to invalidate a region of a texture image or buffer object data store.

Requires OpenGL 2.0. Promoted to core in OpenGL 4.3.

Method Summary

Modifier and Type	Method and Description
static void	glInvalidateBufferData(int buffer) Invalidates the content of a buffer object's data store.
static void	glInvalidateBufferSubData(int buffer, long offset, long length) Invalidates a region of a buffer object's data store.
static void	glInvalidateFramebuffer(int target, int attachment) Invalidate the content some or all of a framebuffer object's attachments.
static void	glInvalidateFramebuffer(int target, int[] attachments) Array version of: InvalidateFramebuffer
static void	glInvalidateFramebuffer(int target, java.nio.IntBuffer attachments) Invalidate the content some or all of a framebuffer object's attachments.
static void	glInvalidateSubFramebuffer(int target, int[] attachments, int x, int y, int width, int height) Array version of: InvalidateSubFramebuffer
static void	glInvalidateSubFramebuffer(int target, java.nio.IntBuffer attachments, int x, int y, int width, int height) Invalidates the content of a region of some or all of a framebuffer object's attachments.
static void	glInvalidateSubFramebuffer(int target, int attachment, int x, int y, int width, int height) Invalidates the content of a region of some or all of a framebuffer object's attachments.
static void	glInvalidateTexImage(int texture, int level) Invalidates the entirety of a texture image.
static void	glInvalidateTexSubImage(int texture, int level, int xoffset, int yoffset, int zoffset, int width, int height, int depth) Invalidates a region of a texture image.
static void	nglInvalidateFramebuffer(int target, int numAttachments, long attachments) Unsafe version of: InvalidateFramebuffer
static void	nglInvalidateSubFramebuffer(int target, int numAttachments, long attachments, int x, int y, int width, int height) Unsafe version of: InvalidateSubFramebuffer

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

glInvalidateTexSubImage

public static void glInvalidateTexSubImage(int texture,
                                           int level,
                                           int xoffset,
                                           int yoffset,
                                           int zoffset,
                                           int width,
                                           int height,
                                           int depth)

Invalidates a region of a texture image.

Parameters:

texture - the name of a texture object a subregion of which to invalidate

level - the level of detail of the texture object within which the region resides

xoffset - the X offset of the region to be invalidated

yoffset - the Y offset of the region to be invalidated

zoffset - the Z offset of the region to be invalidated

width - the width of the region to be invalidated

height - the height of the region to be invalidated

depth - the depth of the region to be invalidated

glInvalidateTexImage

public static void glInvalidateTexImage(int texture,
                                        int level)

Invalidates the entirety of a texture image.

Parameters:

texture - the name of a texture object to invalidate

level - the level of detail of the texture object to invalidate

glInvalidateBufferSubData

public static void glInvalidateBufferSubData(int buffer,
                                             long offset,
                                             long length)

Invalidates a region of a buffer object's data store.

Parameters:

buffer - the name of a buffer object, a subrange of whose data store to invalidate

offset - the offset within the buffer's data store of the start of the range to be invalidated

length - the length of the range within the buffer's data store to be invalidated

glInvalidateBufferData

public static void glInvalidateBufferData(int buffer)

Invalidates the content of a buffer object's data store.

Parameters:

buffer - the name of a buffer object whose data store to invalidate

nglInvalidateFramebuffer

public static void nglInvalidateFramebuffer(int target,
                                            int numAttachments,
                                            long attachments)

Unsafe version of: InvalidateFramebuffer

Parameters:

numAttachments - the number of entries in the attachments array

glInvalidateFramebuffer

public static void glInvalidateFramebuffer(int target,
                                           java.nio.IntBuffer attachments)

Invalidate the content some or all of a framebuffer object's attachments.

Parameters:

target - the target to which the framebuffer is attached. One of:

FRAMEBUFFER

DRAW_FRAMEBUFFER

READ_FRAMEBUFFER

attachments - the address of an array identifying the attachments to be invalidated

glInvalidateFramebuffer

public static void glInvalidateFramebuffer(int target,
                                           int attachment)

Invalidate the content some or all of a framebuffer object's attachments.

Parameters:

target - the target to which the framebuffer is attached. One of:

FRAMEBUFFER

DRAW_FRAMEBUFFER

READ_FRAMEBUFFER

nglInvalidateSubFramebuffer

public static void nglInvalidateSubFramebuffer(int target,
                                               int numAttachments,
                                               long attachments,
                                               int x,
                                               int y,
                                               int width,
                                               int height)

Unsafe version of: InvalidateSubFramebuffer

Parameters:

numAttachments - the number of entries in the attachments array

glInvalidateSubFramebuffer

public static void glInvalidateSubFramebuffer(int target,
                                              java.nio.IntBuffer attachments,
                                              int x,
                                              int y,
                                              int width,
                                              int height)

Invalidates the content of a region of some or all of a framebuffer object's attachments.

Parameters:

target - the target to which the framebuffer is attached. One of:

FRAMEBUFFER

DRAW_FRAMEBUFFER

READ_FRAMEBUFFER

attachments - an array identifying the attachments to be invalidated

x - the X offset of the region to be invalidated

y - the Y offset of the region to be invalidated

width - the width of the region to be invalidated

height - the height of the region to be invalidated

glInvalidateSubFramebuffer

public static void glInvalidateSubFramebuffer(int target,
                                              int attachment,
                                              int x,
                                              int y,
                                              int width,
                                              int height)

Invalidates the content of a region of some or all of a framebuffer object's attachments.

Parameters:

target - the target to which the framebuffer is attached. One of:

FRAMEBUFFER

DRAW_FRAMEBUFFER

READ_FRAMEBUFFER

x - the X offset of the region to be invalidated

y - the Y offset of the region to be invalidated

width - the width of the region to be invalidated

height - the height of the region to be invalidated

glInvalidateFramebuffer

public static void glInvalidateFramebuffer(int target,
                                           int[] attachments)

Array version of: InvalidateFramebuffer

glInvalidateSubFramebuffer

public static void glInvalidateSubFramebuffer(int target,
                                              int[] attachments,
                                              int x,
                                              int y,
                                              int width,
                                              int height)

Array version of: InvalidateSubFramebuffer