5.4 Locking buffers

In order to read or update a hardware buffer, you have to ’lock’ it. This performs 2 functions - it tells the card that you want access to the buffer (which can have an effect on its rendering queue), and it returns a pointer which you can manipulate. Note that if you’ve asked to read the buffer (and remember, you really shouldn’t unless you’ve set the buffer up with a shadow buffer), the contents of the hardware buffer will have been copied into system memory somewhere in order for you to get access to it. For the same reason, when you’re finished with the buffer you must unlock it; if you locked the buffer for writing this will trigger the process of uploading the modified information to the graphics hardware.

Lock parameters

When you lock a buffer, you call one of the following methods:

// Lock the entire buffer
pBuffer->lock(lockType);
// Lock only part of the buffer
pBuffer->lock(start, length, lockType);

The first call locks the entire buffer, the second locks only the section from ’start’ (as a byte offset), for ’length’ bytes. This could be faster than locking the entire buffer since less is transferred, but not if you later update the rest of the buffer too, because doing it in small chunks like this means you cannot use HBL_DISCARD (see below).

The lockType parameter can have a large effect on the performance of your application, especially if you are not using a shadow buffer.

HBL_NORMAL

This kind of lock allows reading and writing from the buffer - it’s also the least optimal because basically you’re telling the card you could be doing anything at all. If you’re not using a shadow buffer, it requires the buffer to be transferred from the card and back again. If you’re using a shadow buffer the effect is minimal.

HBL_READ_ONLY

This means you only want to read the contents of the buffer. Best used when you created the buffer with a shadow buffer because in that case the data does not have to be downloaded from the card.

HBL_DISCARD

This means you are happy for the card to discard the entire current contents of the buffer. Implicitly this means you are not going to read the data - it also means that the card can avoid any stalls if the buffer is currently being rendered from, because it will actually give you an entirely different one. Use this wherever possible when you are locking a buffer which was not created with a shadow buffer. If you are using a shadow buffer it matters less, although with a shadow buffer it’s preferable to lock the entire buffer at once, because that allows the shadow buffer to use HBL_DISCARD when it uploads the updated contents to the real buffer.

HBL_NO_OVERWRITE

This is useful if you are locking just part of the buffer and thus cannot use HBL_DISCARD. It tells the card that you promise not to modify any section of the buffer which has already been used in a rendering operation this frame. Again this is only useful on buffers with no shadow buffer.

Once you have locked a buffer, you can use the pointer returned however you wish (just don’t bother trying to read the data that’s there if you’ve used HBL_DISCARD, or write the data if you’ve used HBL_READ_ONLY). Modifying the contents depends on the type of buffer, See section Hardware Vertex Buffers and See section Hardware Index Buffers

This document was generated on August 20, 2012 using texi2html 5.0.