EngAllocPrivateUserMem macro (winddi.h)

Article
02/22/2024

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