EngAllocPrivateUserMem macro (winddi.h)
The EngAllocPrivateUserMem function allocates a block of user memory from the address space of a specified process and inserts a caller-supplied tag before the allocation.
Syntax
void EngAllocPrivateUserMem(
[in] psl,
[in] cj,
[in] tag
);
Parameters
[in] psl
Pointer to the DD_SURFACE_LOCAL structure representing the Microsoft DirectDraw surface with which to associate the allocated memory.
[in] cj
Specifies the number of bytes of memory to allocate.
[in] tag
Specifies a 4-byte pool tag that uniquely identifies the driver that does the memory allocation. For more information about pool tags, see ExAllocatePoolWithTag.
Return value
None
Remarks
A DirectDraw driver might require a user-memory "scratch pad" in place of true video memory. Although this practice is discouraged due to its performance implications, it is occasionally necessary. This scratch memory is usually allocated only for a short period of time. After the memory has been allocated, it is used for the intended graphics operations, and then deallocated.
A problem arises if the driver instance is destroyed before the surface is unlocked. A particular case occurs when the system switches to a protected desktop as a result of a user pressing CTRL+ALT+DEL. In this situation, the mode switch is performed on a system process context. If the driver has any outstanding surface locks, such as when the mode switch happens before the surface has been unlocked, the driver will be required to destroy that surface on a different process context. The driver cannot call EngFreeUserMem to deallocate the scratch memory since this entry point will fail if called on a different context from that used when the memory was allocated.
EngAllocPrivateUserMem, and EngFreePrivateUserMem are provided to address this problem. These two functions are identical to EngAllocUserMem and EngFreeUserMem, except that they do the extra work required to free memory allocated on a different process context. Process context information is stored with the DirectDraw object that owns the DirectDraw surface object to which psl points.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Windows 2000 and later versions of the Windows operating systems. |
| Target Platform | Universal |
| Header | winddi.h (include Winddi.h) |
| Library | Win32k.lib |
| DLL | Win32k.sys |