 |
NVIDIA DRIVE 5.0 Linux SDK API Reference5.0.10.3 Release |
|
|
NVIDIA DRIVE 5.0 Linux SDK API Reference5.0.10.3 Release |
The Screen Capture API is implemented by the Screen Capture wrapper library, libnvscrncapt.so.
Its functions and data structures are declared by the this header file, which applications must include to use the Screen Capture API.
A screen capture operation consists of three API calls to:
A screen capture operation is initiated by a call to NvScrncaptInit(), which creates an instance of NvScrncaptResult and initializes some of its members. The Screen Capture API returns screen images to the application in this buffer. All subsequent calls to the Screen Capture API require an argument that points to the structure.
After a successful return from NvScrncaptInit(), the application may populate userAddress and userDataSize to specify a preallocated, user-supplied screen capture buffer. If the application supplies a screen capture buffer it is responsible for managing the buffer and freeing the buffer when the screen capture operation concludes. If the application does not supply a buffer, the API allocates and manages the buffer itself.
To perform a capture operation, call the NvScrncaptCapture() function.
If the call succeeds, it:
result->numHeads to indicate the number of heads captured.result->heads[] to represent the screen capture on each captured head. Element 0 represents the first captured head, element 1 represents the second, and so on. Thus the function sets elements 0 through numHeads 1.If the call fails, it returns a non-zero status code.
If screen captures are stored in NvScrncaptSurfaceLayout_BlockLinear surface layout format, then applications must call the NvScrncaptGetBlocklinearOffset() function to calculate the byte offset to a pixel.
Call the NvScrncaptCleanup() function to conclude the screen capture operation. This call frees the screen capture buffer created by the NvScrncaptCapture() function and releases control of the kernel screen capture functionality.
An application may allocate and manage its own screen buffer rather than let the Screen Capture API do so. If the application allocates its own buffer, before it calls the NvScrncaptCapture() function, it must store the buffer's address in result->userAddress and its size in result->userDataSize.
The buffer must be large enough to hold all of the screen images to be captured to succeed. A good way to estimate the size required is to perform a screen capture operation in which the API is allowed to manage the buffer and then examine result->stats.memSize before calling the NvScrncaptCleanup() function.
If the application allocates its own screen buffer, it is responsible for freeing the buffer after it calls the NvScrncaptCleanup() function.
The following sections describe the major data structures and functions in the Screen Capture API, which assume that the API creates and manages the buffer. A sample application is provided as an example of how to use the API.
Data Structures | |
| struct | NvScrncaptPixel |
| Holds a pixel value. More... | |
| struct | NvScrncaptSurfaceMap |
| Holds planes within the frame buffer. More... | |
| struct | NvScrncaptAperture |
| Holds the representation of a display aperture. More... | |
| struct | NvScrncaptWindowState |
| Holds the representation of a window's current state. More... | |
| struct | NvScrncaptHeadState |
| Holds a head's current state. More... | |
| struct | NvScrncaptStatistics |
| Holds statistics for a single capture. More... | |
| struct | NvScrncaptResult |
| Holds the screen capture result. More... | |
Macros | |
| #define | NVSCRNCAPT_VERSION_MAJOR 1 |
| Major Version number. More... | |
| #define | NVSCRNCAPT_VERSION_MINOR 0 |
| Minor Version number. More... | |
| #define | NVSCRNCAPT_TRUE |
| A true NvScrncaptBool value. More... | |
| #define | NVSCRNCAPT_FALSE |
| A false NvScrncaptBool value. More... | |
| #define | NVSCRNCAPT_MAX_HEADS |
| Max # of Display Heads. More... | |
| #define | NVSCRNCAPT_MAX_WINS |
| Max # of Windows. More... | |
Typedefs | |
| typedef int | NvScrncaptBool |
| A boolean value, holding NVSCRNCAPT_TRUE or NVSCRNCAPT_FALSE. More... | |
Functions | |
| NvScrncaptStatus | NvScrncaptInit (NvScrncaptResult **pResult) |
| Initializes data structures required for screen capture. More... | |
| NvScrncaptStatus | NvScrncaptCapture (NvScrncaptResult *result, unsigned int headMask) |
| Conducts screen capture on heads selected by input bitmask. More... | |
| NvScrncaptStatus | NvScrncaptCleanup (NvScrncaptResult *result) |
| Cleans up associated data structures and releases exclusive hold on screen capture functionality. More... | |
| unsigned int | NvScrncaptGetBlocklinearOffset (unsigned int x, unsigned int y, unsigned int stride, unsigned int blockHeight) |
| Auxiliary function to calculate byte offset for a pixel for NvScrncaptSurfaceLayout_BlockLinear surface format. More... | |
| #define NVSCRNCAPT_FALSE |
A false NvScrncaptBool value.
Definition at line 117 of file nvscrncapt.h.
| #define NVSCRNCAPT_MAX_HEADS |
Max # of Display Heads.
Definition at line 120 of file nvscrncapt.h.
| #define NVSCRNCAPT_MAX_WINS |
Max # of Windows.
Definition at line 122 of file nvscrncapt.h.
| #define NVSCRNCAPT_TRUE |
A true NvScrncaptBool value.
Definition at line 115 of file nvscrncapt.h.
| #define NVSCRNCAPT_VERSION_MAJOR 1 |
Major Version number.
Definition at line 110 of file nvscrncapt.h.
| #define NVSCRNCAPT_VERSION_MINOR 0 |
Minor Version number.
Definition at line 112 of file nvscrncapt.h.
| typedef int NvScrncaptBool |
A boolean value, holding NVSCRNCAPT_TRUE or NVSCRNCAPT_FALSE.
Definition at line 128 of file nvscrncapt.h.
| enum NvScrncaptBlend |
Defines the set of blend modes possible for a window.
| Enumerator | |
|---|---|
| NvScrncaptBlend_None | |
| NvScrncaptBlend_Premult | |
| NvScrncaptBlend_Coverage | |
| NvScrncaptBlend_Colorkey | |
Definition at line 226 of file nvscrncapt.h.
Defines the set of pixel color formats, which must be kept in sync with the kernel defines.
Definition at line 170 of file nvscrncapt.h.
| enum NvScrncaptStatus |
Defines the set of all possible error codes.
Definition at line 134 of file nvscrncapt.h.
Defines the set of frame buffer memory layout types.
| Enumerator | |
|---|---|
| NvScrncaptSurfaceLayout_Tiled | |
| NvScrncaptSurfaceLayout_PitchLinear | |
| NvScrncaptSurfaceLayout_BlockLinear | |
Definition at line 160 of file nvscrncapt.h.
| NvScrncaptStatus NvScrncaptCapture | ( | NvScrncaptResult * | result, |
| unsigned int | headMask | ||
| ) |
Conducts screen capture on heads selected by input bitmask.
To use a pre-allocated buffer for capture, populate the result data structure with userAddress and userDataSize prior to this call.
| [in] | result | A pointer to a NvScrncaptResult object. |
| [in] | headMask | A bitmask specifying on which heads to perform the screen capture. A "1" bit specifies to capture the corresponding head. The low order bit represents head 0, the next bit represents head 1, and so on. Thus, for example, a bit mask of 0x05 tells the API to capture images for head 0 and head 2. |
| NvScrncaptStatus NvScrncaptCleanup | ( | NvScrncaptResult * | result | ) |
Cleans up associated data structures and releases exclusive hold on screen capture functionality.
Library-allocated buffers are freed upon this call. In case of pre-allocated user buffers, caller is responsible for freeing these buffers upon return of this call.
| [in] | result | A pointer to a NvScrncaptResult object |
| unsigned int NvScrncaptGetBlocklinearOffset | ( | unsigned int | x, |
| unsigned int | y, | ||
| unsigned int | stride, | ||
| unsigned int | blockHeight | ||
| ) |
Auxiliary function to calculate byte offset for a pixel for NvScrncaptSurfaceLayout_BlockLinear surface format.
The return value is the byte offset to the pixel from the start of screen image. The values of stride and blockHeight can be obtained from the NvScrncaptSurfaceMap structure for the plane.
See the sample application GetPixelRGB() and GetPixelYUV() functions for examples of how to obtain these values.
| [in] | x | Specifies the horizontal x byte position |
| [in] | y | Specifies the vertical y position |
| [in] | stride | Specifies the stride of current plane (length of a row of pixels in bytes. |
| [in] | blockHeight | Specifies the block height value of the block linear surface. |
| NvScrncaptStatus NvScrncaptInit | ( | NvScrncaptResult ** | pResult | ) |
Initializes data structures required for screen capture.
This call creates an instance of struct NvScrncaptResult, which is the central data structure for the Screen Capture API.
| [out] | pResult | A double pointer to a NvScrncaptResult object to get the allocated one |