The AccessDrawableSurface() function is used to gain free access to the bitmap
data of any given render object. 'Free access' means that the graphics data
will not be locked or synchronised while you have access to it, effectively
allowing other tasks to also use the bitmap at the same time. This can be
extremely useful for unsynchronised, high speed read/write access. However,
the lack of synchronisation means that if multiple tasks are using the bitmap
at once, you may encounter inconsistent results.
The surface information is returned in a BitmapSurface structure. More
information on this structure is available in the documentation for the
Bitmap module's BlitSurface() function.
After you have finished with the bitmap, you must match this function with
a call to ReleaseDrawableSurface. Multiple calls to AccessDrawableSurface will
nest. Never re-use the BitmapSurface structure when making calls to this
function.
If you would like your bitmap access to be synchronised, use the
LockDrawableBitmap() function instead.
ERR_Okay | Access successful. |
ERR_Args | Invalid arguments were supplied. |
ERR_Search | The supplied RenderID did not refer to a recognised render object. |
ERR_AccessMemory | Failed to access the internal renderlist memory structure, or the bitmap data was not accessible. |
|