Chapter 8 Video I/O Control Codes
This chapter summarizes the public IOCTL_VIDEO_XXX requests that video miniport drivers handle. Every video miniport driver must provide support for at least the following requests:
·IOCTL_VIDEO_MAP_VIDEO_MEMORY
·IOCTL_VIDEO_UNMAP_VIDEO_MEMORY
·IOCTL_VIDEO_QUERY_NUM_AVAIL_MODES
·IOCTL_VIDEO_QUERY_AVAIL_MODES
·IOCTL_VIDEO_QUERY_CURRENT_MODE
·IOCTL_VIDEO_SET_CURRENT_MODE
·IOCTL_VIDEO_RESET_DEVICE
Depending on the adapter features, a miniport driver can be required to support additional IOCTL_VIDEO_XXX requests, while support for others is optional.
For information on the design of display drivers and video miniport drivers, see the Graphics Driver Design Guide.
Operation
Makes the cursor invisible: that is, disables the cursor's visibility attribute. Miniport drivers for VGA-compatible adapters are required to support this request, which is modal. Support is optional for other miniport drivers.
Input
None
Output
None
Status Block
The miniport driver does not set the Information field.
Operation
Makes the pointer invisible: that is, disables pointer attributes. Supports for this request, which is modal, is optional.
Input
None
Output
None
Status Block
The miniport driver does not set the Information field.
Operation
Makes the cursor visible: that is, enables the cursor's visibility attribute. Miniport drivers for VGA-compatible adapters are required to support this request, which is modal. Support is optional for other miniport drivers.
Input
None
Output
None
Status Block
The miniport driver does not set the Information field.
Operation
Makes the pointer visible: that is, enables pointer attributes. Support for this request, which is modal, is optional. However, if a miniport driver supports this request, it must process an IOCTL_VIDEO_SET_POINTER_ATTR request before processing this request.
Input
None
Output
None
Status Block
The miniport driver does not set the Information field.
IOCTL_VIDEO_FREE_PUBLIC_ACCESS_RANGES
Operation
Releases the address range that was allocated by a preceding IOCTL_VIDEO_QUERY_PUBLIC_ACCESS_RANGES request. Support for this request, which is nonmodal, is optional.
Input
The VRP InputBuffer contains an array of VIDEO_PUBLIC_ACCESS_RANGES to be released.
Output
None
Status Block
The miniport driver does not set the Information field.
IOCTL_VIDEO_GET_BANK_SELECT_CODE
Operation
Returns a block of x86-specific executable code to be used by a high-resolution SVGA display driver for bank-switching. Miniport drivers for VGA-compatible adapters are required to support this request, which is modal. It is optional for other miniport drivers. On RISC-based machines, this request is a no-op.
Input
None
Output
The miniport driver returns the VIDEO_BANK_SELECT information in the VRP OutputBuffer.
Status Block
If the miniport driver returns its code block, it sets the Information field to sizeof(VIDEO_BANK_SELECT). Otherwise, the miniport driver sets the Information field to zero.
IOCTL_VIDEO_GET_POWER_MANAGEMENT
Operation
Returns the current power-consumption level of the adapter. Support for this IOCTL, which is nonmodal, is required for adapters that conform to the VESA DPMS standard.
Input
None
Output
The miniport driver returns the VIDEO_POWER_MANAGEMENT information in the VRP OutputBuffer.
Status Block
If the miniport driver successfully returns the power-consumption information, it sets the Information field to sizeof(VIDEO_POWER_MANAGEMENT). Otherwise, the miniport driver sets the Information field to zero.
Operation
Loads a user-defined font on the adapter. Miniport drivers for VGA-compatible adapters are required to support this request, which is modal. Support is optional for other miniport drivers.
Input
The VRP InputBuffer contains the VIDEO_LOAD_FONT_INFORMATION describing the font's width, height, and size, as well as a pointer to the font buffer.
Output
None
Status Block
The miniport driver does not set the Information field.
Operation
Maps the video hardware frame buffer and video RAM into the virtual address space of the requestor. Miniport drivers are required to handle this IOCTL and to map all video memory in the caller's address space with VideoPortMapMemory. This request is both modal and nonmodal: the miniport driver must return the location size of the frame buffer within video memory, and the frame buffer size and location can vary from mode to mode (modal characteristic), but a subsequent set-mode operation (to the same mode) must not cause the video memory to change location (nonmodal characteristic).
Input
The VRP InputBuffer contains a VIDEO_MEMORY structure specifying either a requested virtual base address or zero, which requests the system to assign a virtual base address mapped to the adapter's RAM and frame buffer range(s).
Output
The miniport driver returns the VIDEO_MEMORY_INFORMATION in the VRP OutputBuffer.
Status Block
If the miniport driver successfully maps the memory, it sets the Information field to sizeof(VIDEO_MEMORY_INFORMATION). Otherwise, it sets the Information field to zero.
Operation
None. This request is obsolete.
Operation
Returns information about each video mode supported by the adapter. Miniport drivers are required to support this request, which is nonmodal.
Input
None
Output
The miniport driver returns an array of VIDEO_MODE_INFORMATION-type elements in the VRP OutputBuffer.
Status Block
If the miniport driver successfully returns the available modes, it sets the Information field to (sizeof(VIDEO_MODE_INFORMATION) * NumberOfSupportedModes). Otherwise, the miniport driver sets the Information field to zero.
IOCTL_VIDEO_QUERY_COLOR_CAPABILITIES
Operation
Returns the color-capabilities information found in the VDDP description file for the adapter. Support for this request, which is nonmodal, is optional. However, if a miniport driver supports this request, it cannot return a subset of the color-capabilities information.
Input
None
Output
The miniport driver returns all VIDEO_COLOR_CAPABILITIES information in the VRP OutputBuffer.
Status Block
If the miniport driver successfully returns the color-capabilities data, it sets the Information field to sizeof(VIDEO_COLOR_CAPABILITIES). Otherwise, the miniport driver sets the Information field to zero.
IOCTL_VIDEO_QUERY_CURRENT_FONT
Operation
None. This request is obsolete.
IOCTL_VIDEO_QUERY_CURRENT_MODE
Operation
Returns information about the current adapter mode. Miniport drivers are required to support this request, which is modal.
Input
None
Output
The miniport driver returns the VIDEO_MODE_INFORMATION in the VRP OutputBuffer.
Status Block
If the miniport driver successfully returns the mode data, it sets the Information field to sizeof(VIDEO_MODE_INFORMATION). Otherwise, the miniport driver sets the Information field to zero.
Operation
Returns the size, position, and visibility of the cursor. Miniport drivers for VGA-compatible adapters are required to support this request, which is modal. Support is optional for other miniport drivers. The cursor position is specified by top and bottom scan lines, instead of row and column information, for VGA-compatible adapters.
Input
None
Output
The miniport driver returns the VIDEO_CURSOR_ATTRIBUTES information in the VRP OutputBuffer.
Status Block
If the miniport driver successfully returns the cursor-attribute data, it sets the Information field to sizeof(VIDEO_CURSOR_ATTRIBUTES). Otherwise, the miniport driver sets the Information field to zero.
IOCTL_VIDEO_QUERY_CURSOR_POSITION
Operation
Returns the current cursor position (row and column). Miniport drivers for VGA-compatible adapters are required to support this request, which is modal. It is optional for other miniport drivers.
Input
None
Output
The miniport driver returns the VIDEO_CURSOR_POSITION information in the VRP OutputBuffer.
Status Block
If the miniport driver successfully returns the cursor position, it sets the Information field to sizeof(VIDEO_CURSOR_POSITION). Otherwise, the miniport driver sets the Information field to zero.
IOCTL_VIDEO_QUERY_NUM_AVAIL_FONTS
Operation
None. This request is obsolete.
IOCTL_VIDEO_QUERY_NUM_AVAIL_MODES
Operation
Returns the number of video modes supported by the adapter and the size in bytes of the video mode information, which can be used to allocate a buffer for an IOCTL_VIDEO_QUERY_AVAIL_MODES request. Miniport drivers are required to support this request, which is nonmodal.
Input
None
Output
The miniport driver returns the VIDEO_NUM_MODES in the VRP OutputBuffer.
Status Block
If the miniport driver successfully returns the mode count, it sets the Information field to sizeof(VIDEO_NUM_MODES). Otherwise, the miniport driver sets the Information field to zero.
IOCTL_VIDEO_QUERY_POINTER_ATTR
Operation
Returns the attributes for the pointer, defined as a set of pixels used to paint the shape associated with the mouse. Support for this request, which is modal, is optional.
Input
None
Output
The miniport driver returns the VIDEO_POINTER_ATTRIBUTES information in the VRP OutputBuffer.
Status Block
If the miniport driver successfully returns the pointer attributes, it sets the Information field to sizeof(VIDEO_POINTER_ATTRIBUTES). Otherwise, the miniport driver sets the Information field to zero.
IOCTL_VIDEO_QUERY_POINTER_CAPABILITIES
Operation
Returns information about the adapter's "hardware cursor" features. Support for this request, which is modal, is optional.
Input
None
Output
The miniport driver returns the VIDEO_POINTER_CAPABILITIES information in the VRP OutputBuffer.
Status Block
If the miniport driver successfully returns the pointer capabilities, it sets the Information field to sizeof(VIDEO_POINTER_CAPABILITIES). Otherwise, the miniport driver sets the Information field to zero.
IOCTL_VIDEO_QUERY_POINTER_POSITION
Operation
Returns the current position of the pointer. Support for this request, which is modal, is optional.
Input
None
Output
The miniport driver returns the VIDEO_POINTER_POSITION information in the VRP OutputBuffer.
Status Block
If the miniport driver successfully returns the pointer position, it sets the Information field to sizeof(VIDEO_POINTER_POSITION). Otherwise, the miniport driver sets the Information field to zero.
IOCTL_VIDEO_QUERY_PUBLIC_ACCESS_RANGES
Operation
Returns an array, possibly with one element, of address ranges used to program the adapter registers or ports directly. Support for this request, which is nonmodal, is optional.
Input
None
Output
The miniport driver returns an array of VIDEO_PUBLIC_ACCESS_RANGES in the VRP OutputBuffer.
Status Block
If the miniport driver returns address range(s), it sets the Information field to sizeof(VIDEO_PUBLIC_ACCESS_RANGES). Otherwise, the miniport driver sets the Information field to zero.
Operation
Resets the video hardware to the default mode, to which it was initialized at system boot. Miniport drivers are required to support this request, which is nonmodal.
Input
None
Output
None
Status Block
The miniport driver does not set the Information field.
IOCTL_VIDEO_RESTORE_HARDWARE_STATE
Operation
Restores all values used to set the hardware registers. Miniport drivers for VGA-compatible adapters are required to support this request, which is nonmodal. It is optional for other miniport drivers.
Input
The VRP InputBuffer contains the VIDEO_HARDWARE_STATE previously saved.
Output
None
Status Block
The miniport driver does not set the Information field.
IOCTL_VIDEO_SAVE_HARDWARE_STATE
Operation
Saves the state of the video adapter in the VRP OutputBuffer. Miniport drivers for VGA-compatible adapters are required to support this request, which is nonmodal. Support is optional for other miniport drivers.
Input
None
Output
The miniport driver returns the VIDEO_HARDWARE_STATE information in the VRP OutputBuffer.
Status Block
If the miniport driver successfully saves the adapter state, it sets the Information field to sizeof(VIDEO_HARDWARE_STATE). Otherwise, the miniport driver sets the Information field to zero.
IOCTL_VIDEO_SET_COLOR_REGISTERS
Operation
Sets the adapter's color registers to the specified RGB values. If the adapter has a CLUT, sometimes called a "palette," the miniport driver is required to support this request, which is modal.
Input
The VRP InputBuffer contains the VIDEO_CLUT, specifying an array of RGB values to be set.
Output
None
Status Block
The miniport driver does not set the Information field.
Operation
None. This request is obsolete.
Operation
Sets the adapter to the specified operating mode. Miniport drivers are required to support this request, which is nonmodal since it resets the current mode. The miniport driver must also consider the two high order flags which are used to additionally control the mode set operation. See VIDEO_MODE for further information.
Input
The VRP InputBuffer contains a VIDEO_MODE structure specifying the mode to be set.
Output
None
Status Block
The miniport driver does not set the Information field.
Operation
Sets the cursor size, position, and visibility. Miniport drivers for VGA-compatible adapters are required to support this request, which is modal. Support is optional for other miniport drivers.
Input
The VRP InputBuffer contains the VIDEO_CURSOR_ATTRIBUTES to be set.
Output
None
Status Block
The miniport driver does not set the Information field.
IOCTL_VIDEO_SET_CURSOR_POSITION
Operation
Sets the cursor position (row and column). Miniport drivers for VGA-compatible adapters are required to support this request, which is modal. It is optional for other miniport drivers.
Input
The VRP InputBuffer contains the VIDEO_CURSOR_POSITION to be set.
Output
None
Status Block
The miniport driver does not set the Information field.
IOCTL_VIDEO_SET_PALETTE_REGISTERS
Operation
Loads a specified portion of the adapter palette registers with an array of colors. Miniport drivers for VGA-compatible adapters are required to support this request, which is modal. Support is optional for other miniport drivers.
Input
The VRP InputBuffer contains the VIDEO_PALETTE_DATA, specifying an array of colors to be set in the palette registers.
Output
None
Status Block
The miniport driver does not set the Information field.
Operation
Sets the pointer attributes. Support for this request, which is modal, is optional. A supporting miniport driver can fail this request (for example, if the attributes specify a larger pointer than the miniport driver can supply). When a miniport driver fails this request, the corresponding display driver must manage the pointer.
Input
The VRP InputBuffer contains the VIDEO_POINTER_ATTRIBUTES to be set.
Output
None
Status Block
The miniport driver does not set the Information field.
IOCTL_VIDEO_SET_POINTER_POSITION
Operation
Sets the pointer position. Support for this request, which is modal, is optional. A supporting miniport driver should have already processed an enable-pointer request before processing this request.
Input
The VRP InputBuffer contains the VIDEO_POINTER_POSITION to be set.
Output
None
Status Block
The miniport driver does not set the Information field.
IOCTL_VIDEO_SET_POWER_MANAGEMENT
Operation
Resets the power-consumption level of the adapter to the specified state. As long as the state is VideoPowerOff, the port driver intercepts and fails all IOCTL_VIDEO_XXX requests to the miniport driver until the next IOCTL_VIDEO_SET_POWER_MANAGEMENT request that resets the state to a power-on condition.
Input
The VRP InputBuffer contains the VIDEO_POWER_MANAGEMENT structure, specifying the state to be set.
Output
None
Status Block
The miniport driver does not set the Information field.
IOCTL_VIDEO_SHARE_VIDEO_MEMORY
Operation
This IOCTL is called by a process that will share video memory as a linear frame buffer. Miniport drivers handle this IOCTL by mapping the frame buffer into the caller's address space with VideoPortMapBankedMemory. Otherwise this IOCTL is the same as IOCTL_VIDEO_MAP_VIDEO_MEMORY.
This request is both modal and nonmodal: the miniport driver must return the location size of the frame buffer within video memory, and the frame buffer size and location can vary from mode to mode (modal characteristic), but a subsequent set-mode operation (to the same mode) must not cause the video memory to change location (nonmodal characteristic)
This IOCTL is DCI only.
Input
The VRP InputBuffer contains a VIDEO_SHARE_MEMORY structure specifying a handle to the process mapping the frame buffer, and the requested view size and offset into the shared memory. The view size plus the offset must not exceed the memory size of the adapter.
Output
The miniport driver returns the VIDEO_MEMORY_INFORMATION structure in the VRP OutputBuffer. This output contains the virtual address where the video memory is mapped, the view size in bytes of the mapped memory and the offset into the view.
Status Block
If the miniport driver successfully maps the memory, it sets the Information field to sizeof(VIDEO_SHARE_MEMORY_INFORMATION). Otherwise, the miniport driver sets the Information field to zero.
IOCTL_VIDEO_UNMAP_VIDEO_MEMORY
Operation
Releases a mapping between the virtual address space and the adapter's frame buffer and video RAM. Miniport drivers are required to support this request, which is nonmodal.
Input
The VRP InputBuffer contains the VIDEO_MEMORY, specifying the previously mapped virtual base address to be released with VideoPortUnmapMemory.
Output
None
Status Block
The miniport driver does not set the Information field.
IOCTL_VIDEO_UNSHARE_VIDEO_MEMORY
Operation
Unmaps a video hardware frame buffer and video RAM from the virtual address space of the requestor that was mapped by an IOCTL_VIDEO_SHARE_VIDEO_MEMORY request.
Input
The VRP InputBuffer contains a VIDEO_MEMORY structure specifying the process and the virtual address where the video memory is mapped. The memory is unmapped by calling VideoPortUnmapMemory.
Output
None.
Status Block
The miniport driver does not set the Information field.