blob: 16ed058b365d29927f455be974c50438cb051467 [file] [log] [blame]
Name
AMD_pinned_memory
Name Strings
GL_AMD_pinned_memory
Contributors
Pierre Boudier
Graham Sellers
Contact
Pierre Boudier, AMD (pierre.boudier 'at' amd.com)
IP Status
None.
Status
Shipping
Version
Last Modified Date: June 4, 2013
Revision: 2.0
Number
411
Dependencies
This specification is written against the OpenGL 4.2 (Core) Specification,
dated August 8, 2011.
Overview
This extension defines an interface that allows improved control
of the physical memory used by the graphics device.
It allows an existing page of system memory allocated by the application
to be used as memory directly accessible to the graphics processor. One
example application of this functionality would be to be able to avoid an
explicit synchronous copy with sub-system of the application; for instance
it is possible to directly draw from a system memory copy of a video
image.
New Procedures and Functions
None
New Tokens
Accepted by the <target> parameters of BindBuffer, BufferData,
BufferSubData, MapBuffer, UnmapBuffer, GetBufferSubData,
GetBufferParameteriv, GetBufferPointerv, MapBufferRange:
EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD 0x9160
Additions to Chapter 2 of the OpenGL 4.2 (Core Profile) Specification
(OpenGL Operation)
Additions to the table Table 2.8: Buffer object binding targets.
+-------------------------------------+---------------------------------+-------------------------+
| Target name | Purpose | Described in section(s) |
+-------------------------------------+---------------------------------+-------------------------+
| EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD | Application-owned memory buffer | 2.9.2 |
+-------------------------------------+---------------------------------+-------------------------+
Modifications to Section 2.9.2, "Creating Buffer Object Data Stores"
2.9.2 Creating Buffer Object Data Stores
The data store of a buffer object is created and initialized by calling
void BufferData( enum target, sizeiptr size, const void *data, enum usage );
with <target> set to one of the targets listed in table 2.8, <size> set to
the size of the data store in basic machine units, and data pointing to the
source data in client memory. If <target> is not
EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD, then if <data> is non-null, the source
data is copied to the buffer object's data store. If <data> is null, then
the contents of the buffer object's data store are undefined. If <target>
is EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD, then the client's memory is used
directly by the GL for all subsequent operations on the buffer object's
data store. In this case, the application must guarantee the existence of
the buffer for the lifetime of the buffer object, or until its data store
is re-specified by another call to BufferData. <usage> is specified as one
of nine enumerated values, indicating the expected application usage
pattern of the data store. The values are: ...
Additions to Chapter 3 of the OpenGL 4.2 (Core Profile) Specification
(Rasterization)
None.
Additions to Chapter 4 of the OpenGL 4.2 (Core Profile) Specification
(Per-Fragment Operations and the Framebuffer)
None.
Additions to Chapter 5 of the OpenGL 4.2 (Core Profile) Specification
(Special Functions)
None.
Additions to Chapter 6 of the OpenGL 4.2 (Core Profile) Specification
(State and State Requests)
None.
Errors
INVALID_OPERATION is generated by BufferData if <target> is
EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD, and the store cannot be mapped to the
GPU address space.
Issues
1) When a system memory is shared with the GL, do we need extra
synchronization for the application to update the content?
RESOLVED: NO. once the memory page has been shared with the GL,
then all the regular OpenGL commands can be used to ensure
proper synchronization. the newly created buffer object is
no different from the ones that were allocated by GL, except
that the physical pages cannot be changed (but virtual mapping
can change).
2) Can the application still use the buffer using the CPU address?
RESOLVED: YES. However, this access would be completely
non synchronized to the OpenGL pipeline, unless explicit
synchronization is being used (for example, through glFinish or by using
sync objects).
3) Can the application free the memory?
RESOLVED: YES. However, the underlying buffer object should
have been deleted from the OpenGL to prevent any access by
the GPU, or the result is undefined, including program or even system
termination.
4) Is glMapBuffer on a shared buffer guaranteed to return the same system
address which was specified at creation time?
RESOLVED: NO. The GL implementation might return a different virtual
mapping of that memory, although the same physical page will be used.
5) Is there any limitation on offset/size?
RESOLVED: YES. Since the pinning of system memory is eventually handled
by the OS, there might be different restriction. It is recommended to
align the offset/size to the underlying page size (4k seems to be
widespread).
6) What happens if you use this extension on two separate buffers which are
sharing the same underlying physical page?
RESOLVED: The behavior is undefined. some OS will not refcount how
many times a physical page is locked for GPU access, and may therefore
either fail to lock, or fail to properly unlock.
7) Should there be a query for the alignment value of offset/size?
RESOLVED: NO. on the same system, it is possible to have several
different page sizes.
8) Why is the error produced for failure to pin memory INVALID_OPERATION?
Why not OUT_OF_MEMORY?
OUT_OF_MEMORY invalidates OpenGL context state. Failure to pin memory
does not upset the state of the context, and so an error that does not
have this semantic was chosen. The exact cause of the failure may be
reported by a debug context.
Example Usage
The GL_EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD target is used simply for the
purposes of allocation through BufferData. It is otherwise not referenced
by the GL (much like GL_COPY_READ_BUFFER, for example). Once the buffer's
data store has been associated with client memory, that memory may be used
for any purpose such as vertex attributes (GL_ARRAY_BUFFER), TBO
(GL_TEXTURE_BUFFER), pixel reads and writes (GL_PIXEL_UNPACK_BUFFER,
GL_PIXEL_PACK_BUFFER) or transform feedback (GL_TRANSFORM_FEEDBACK_BUFFER).
As an example, consider the following example, which performs an
asynchronous pixel readback to client memory:
GLuint buffer;
glGenBuffers(1, &buffer);
glBindBuffer(GL_EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD, buffer);
void * memory = malloc(1024 * 1024 * 4);
glBufferData(GL_EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD, 1024 * 1024 * 4, GL_STREAM_COPY, memory);
glBindBuffer(GL_EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD, 0);
glBindBuffer(GL_PIXEL_PACK_BUFFER_AMD, buffer);
glReadPixels(0, 0, 1024, 1024, GL_RGBA, GL_UNSIGNED_BYTE, 0);
GLsync s = glFenceSync(GL_SYNC_GPU_COMMANDS_COMPLETE, 0);
// Data will eventually end up in 'memory'. Other processing may occur
// during the transfer time.
glClientWaitSync(s, GL_SYNC_FLUSH_COMMANDS_BIT, ~0ull);
// It is now safe to use 'memory'
Revision History
Rev. Date Author Changes
---- -------- -------- -----------------------------------------
2 04/05/2013 gsellers Fixed a couple of typos.
1 11/30/2011 gsellers Cleanup and minor updates.
xx 03/22/2011 pboudier Initial draft.