DiveBeginImageBufferAccess

This function must be called before reading or writing data in a buffer allocated with DiveAllocImageBuffer. Depending on the underlying hardware implementation, this function might result in the frame buffer access being serialized (see DiveAcquireFrameBuffer). Once the caller has completed accessing (reading or writing) the image buffer, DiveEndImageBufferAccess must be called. Note that the pointer to the allocated buffer and line size are returned by this function, and these values might change from one image buffer access to the next.

Syntax

_DiveBeginImageBufferAccess(hDiveInst, ulBufferNumber, ppbImageBuffer, pulBufferScanLineBytes, pulBufferScanLines)

Parameters

hDiveInst (HDIVE) - input

Display engine DIVE instance.

ulBufferNumber (ULONG) - input

DIVE instance buffer number being requested.

ppbImageBuffer (PBYTE*) - output

Pointer to pointer to allocated image buffer on return.

pulBufferScanLineBytes (PULONG) - output

Pointer to scan line size of allocated memory. On some hardware, this memory might not be allocated in a contiguous fashion.

pulBufferScanLines (PULONG) - output

Pointer to number of scan lines in the image buffer.

Returns

rc (ULONG) - returns

Return codes indicating success or type of failure:

• DIVE_SUCCESS If the function succeeds, 0 is returned.
• DIVE_ERR_INVALID_BUFFER_NUMBER The ulBufferNumber parameter must be a previously allocated or associated buffer number before it can be accessed.
• DIVE_ERR_INVALID_INSTANCE The DIVE instance handle specified in the hDiveInst parameter is invalid.

Remarks

This function has no effect if the image buffer was allocated in system memory.

Example Code

#include <dive.h>

HDIVE hDiveInst;                /* Display engine DIVE instance. */
ULONG ulBufferNumber;           /* Buffer number being requested. */
PBYTE *ppbImageBuffer;          /* Pointer to pointer. */
PULONG pulBufferScanLineBytes;  /* Pointer to scan line size. */
PULONG pulBufferScanLines;      /* Pointer to # of scan lines. */
ULONG rc;                       /* Return codes. */

rc = DiveBeginImageBufferAccess(hDiveInst,
        ulBufferNumber, ppbImageBuffer, pulBufferScanLineBytes,
        pulBufferScanLines);