NVIDIA DRIVE 5.0 Linux SDK API Reference

5.0.5.0 Release

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Screen Capture API

Detailed Description

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:

Initiate Screen Capture

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.

Perform Screen Capture

To perform a capture operation, call the NvScrncaptCapture() function.

If the call succeeds, it:

  1. Allocates a screen capture buffer.
  2. Captures the requested screen images in the buffer.
  3. Sets result->numHeads to indicate the number of heads captured.
  4. Sets the elements of 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.
  5. Returns a status code of zero.

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.

Conclude Screen Capture

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.

Allocating and Managing the Screen Capture Buffer

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...
 

Enumerations

enum  NvScrncaptStatus {
  NVSCRNCAPT_STATUS_OK,
  NVSCRNCAPT_STATUS_BAD_PARAMETER,
  NVSCRNCAPT_STATUS_BUSY,
  NVSCRNCAPT_STATUS_TIMED_OUT,
  NVSCRNCAPT_STATUS_OUT_OF_MEMORY,
  NVSCRNCAPT_STATUS_NOT_INITIALIZED,
  NVSCRNCAPT_STATUS_NOT_SUPPORTED,
  NVSCRNCAPT_STATUS_ERROR,
  NVSCRNCAPT_STATUS_INVALID_SIZE,
  NVSCRNCAPT_STATUS_INCOMPATIBLE_VERSION
}
 Defines the set of all possible error codes. More...
 
enum  NvScrncaptSurfaceLayout {
  NvScrncaptSurfaceLayout_Tiled = 0,
  NvScrncaptSurfaceLayout_PitchLinear,
  NvScrncaptSurfaceLayout_BlockLinear
}
 Defines the set of frame buffer memory layout types. More...
 
enum  NvScrncaptColorFormat {
  NvScrncaptColorFormat_RGB_AUTO = ~0,
  NvScrncaptColorFormat_P8 = 3,
  NvScrncaptColorFormat_B4G4R4A4 = 4,
  NvScrncaptColorFormat_B5G5R5A = 5,
  NvScrncaptColorFormat_B5G6R5 = 6,
  NvScrncaptColorFormat_AB5G5R5 = 7,
  NvScrncaptColorFormat_B8G8R8A8 = 12,
  NvScrncaptColorFormat_R8G8B8A8 = 13,
  NvScrncaptColorFormat_B6x2G6x2R6x2A8 = 14,
  NvScrncaptColorFormat_R6x2G6x2B6x2A8 = 15,
  NvScrncaptColorFormat_YCbCr422 = 16,
  NvScrncaptColorFormat_YUV422 = 17,
  NvScrncaptColorFormat_YCbCr420P = 18,
  NvScrncaptColorFormat_YUV420P = 19,
  NvScrncaptColorFormat_YCbCr422P = 20,
  NvScrncaptColorFormat_YUV422P = 21,
  NvScrncaptColorFormat_YCbCr422R = 22,
  NvScrncaptColorFormat_YUV422R = 23,
  NvScrncaptColorFormat_YCbCr422RA = 24,
  NvScrncaptColorFormat_YUV422RA = 25,
  NvScrncaptColorFormat_R4G4B4A4 = 27,
  NvScrncaptColorFormat_R5G5B5A = 28,
  NvScrncaptColorFormat_AR5G5B5 = 29,
  NvScrncaptColorFormat_B5G5R5X = 30,
  NvScrncaptColorFormat_XB5G5R5 = 31,
  NvScrncaptColorFormat_R5G5B5X = 32,
  NvScrncaptColorFormat_XR5G5B5 = 33,
  NvScrncaptColorFormat_R5G6B5 = 34,
  NvScrncaptColorFormat_A8B8G8R8 = 36,
  NvScrncaptColorFormat_B8G8R8X8 = 37,
  NvScrncaptColorFormat_R8G8B8X8 = 38,
  NvScrncaptColorFormat_YCbCr444P = 41,
  NvScrncaptColorFormat_YCrCb420SP = 42,
  NvScrncaptColorFormat_YCbCr420SP = 43,
  NvScrncaptColorFormat_YCrCb422SP = 44,
  NvScrncaptColorFormat_YCbCr422SP = 45,
  NvScrncaptColorFormat_YCrCb422SPR = 46,
  NvScrncaptColorFormat_YCbCr422SPR = 47,
  NvScrncaptColorFormat_YCrCb444SP = 48,
  NvScrncaptColorFormat_YCbCr444SP = 49,
  NvScrncaptColorFormat_YUV444P = 52,
  NvScrncaptColorFormat_YVU420SP = 53,
  NvScrncaptColorFormat_YUV420SP = 54,
  NvScrncaptColorFormat_YVU422SP = 55,
  NvScrncaptColorFormat_YUV422SP = 56,
  NvScrncaptColorFormat_YVU422SPR = 57,
  NvScrncaptColorFormat_YUV422SPR = 58,
  NvScrncaptColorFormat_YVU444SP = 59,
  NvScrncaptColorFormat_YUV444SP = 60
}
 Defines the set of pixel color formats, which must be kept in sync with the kernel defines. More...
 
enum  NvScrncaptBlend {
  NvScrncaptBlend_None,
  NvScrncaptBlend_Premult,
  NvScrncaptBlend_Coverage,
  NvScrncaptBlend_Colorkey
}
 Defines the set of blend modes possible for a window. 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...
 

Macro Definition Documentation

#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 Documentation

typedef int NvScrncaptBool

A boolean value, holding NVSCRNCAPT_TRUE or NVSCRNCAPT_FALSE.

Definition at line 128 of file nvscrncapt.h.

Enumeration Type Documentation

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.

Enumerator
NvScrncaptColorFormat_RGB_AUTO 
NvScrncaptColorFormat_P8 
NvScrncaptColorFormat_B4G4R4A4 
NvScrncaptColorFormat_B5G5R5A 
NvScrncaptColorFormat_B5G6R5 
NvScrncaptColorFormat_AB5G5R5 
NvScrncaptColorFormat_B8G8R8A8 
NvScrncaptColorFormat_R8G8B8A8 
NvScrncaptColorFormat_B6x2G6x2R6x2A8 
NvScrncaptColorFormat_R6x2G6x2B6x2A8 
NvScrncaptColorFormat_YCbCr422 
NvScrncaptColorFormat_YUV422 
NvScrncaptColorFormat_YCbCr420P 
NvScrncaptColorFormat_YUV420P 
NvScrncaptColorFormat_YCbCr422P 
NvScrncaptColorFormat_YUV422P 
NvScrncaptColorFormat_YCbCr422R 
NvScrncaptColorFormat_YUV422R 
NvScrncaptColorFormat_YCbCr422RA 
NvScrncaptColorFormat_YUV422RA 
NvScrncaptColorFormat_R4G4B4A4 
NvScrncaptColorFormat_R5G5B5A 
NvScrncaptColorFormat_AR5G5B5 
NvScrncaptColorFormat_B5G5R5X 
NvScrncaptColorFormat_XB5G5R5 
NvScrncaptColorFormat_R5G5B5X 
NvScrncaptColorFormat_XR5G5B5 
NvScrncaptColorFormat_R5G6B5 
NvScrncaptColorFormat_A8B8G8R8 
NvScrncaptColorFormat_B8G8R8X8 
NvScrncaptColorFormat_R8G8B8X8 
NvScrncaptColorFormat_YCbCr444P 
NvScrncaptColorFormat_YCrCb420SP 
NvScrncaptColorFormat_YCbCr420SP 
NvScrncaptColorFormat_YCrCb422SP 
NvScrncaptColorFormat_YCbCr422SP 
NvScrncaptColorFormat_YCrCb422SPR 
NvScrncaptColorFormat_YCbCr422SPR 
NvScrncaptColorFormat_YCrCb444SP 
NvScrncaptColorFormat_YCbCr444SP 
NvScrncaptColorFormat_YUV444P 
NvScrncaptColorFormat_YVU420SP 
NvScrncaptColorFormat_YUV420SP 
NvScrncaptColorFormat_YVU422SP 
NvScrncaptColorFormat_YUV422SP 
NvScrncaptColorFormat_YVU422SPR 
NvScrncaptColorFormat_YUV422SPR 
NvScrncaptColorFormat_YVU444SP 
NvScrncaptColorFormat_YUV444SP 

Definition at line 170 of file nvscrncapt.h.

Defines the set of all possible error codes.

Enumerator
NVSCRNCAPT_STATUS_OK 

The operation completed successfully; no error.

NVSCRNCAPT_STATUS_BAD_PARAMETER 

Indicates a bad parameter was passed.

NVSCRNCAPT_STATUS_BUSY 

Indicates a the resource is busy.

NVSCRNCAPT_STATUS_TIMED_OUT 

Indicates a operation timed out.

NVSCRNCAPT_STATUS_OUT_OF_MEMORY 

Indicates a an out-of-memory condition.

NVSCRNCAPT_STATUS_NOT_INITIALIZED 

Indicates not initialized.

NVSCRNCAPT_STATUS_NOT_SUPPORTED 

Indicates not supported.

NVSCRNCAPT_STATUS_ERROR 

Indicates a catch-all error, used when no other error code applies.

NVSCRNCAPT_STATUS_INVALID_SIZE 

Indicates invalid size.

NVSCRNCAPT_STATUS_INCOMPATIBLE_VERSION 

Indicates an incompatible version.

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.

Function Documentation

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.

Precondition
The NvScrncaptResult structure has been created by a call to the NvScrncaptInit() function.
Parameters
[in]resultA pointer to a NvScrncaptResult object.
[in]headMaskA 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.
Returns
NvScrncaptStatus The completion status of the operation. Possible values are:
NVSCRNCAPT_STATUS_OK
NVSCRNCAPT_STATUS_NOT_INITIALIZED
NVSCRNCAPT_STATUS_BAD_PARAMETER
NVSCRNCAPT_STATUS_OUT_OF_MEMORY
NVSCRNCAPT_STATUS_ERROR
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.

Parameters
[in]resultA pointer to a NvScrncaptResult object
Returns
NvScrncaptStatus The completion status of the operation. Possible values are:
NVSCRNCAPT_STATUS_OK
NVSCRNCAPT_STATUS_NOT_INITIALIZED
NVSCRNCAPT_STATUS_ERROR
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.

Parameters
[in]xSpecifies the horizontal x byte position
[in]ySpecifies the vertical y position
[in]strideSpecifies the stride of current plane (length of a row of pixels in bytes.
[in]blockHeightSpecifies the block height value of the block linear surface.
Returns
Byte offset of the pixel from start of buffer.
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.

Note
This API takes exclusive hold of screen capture functionality from the kernel. Any future call to the kernel screen capture API will fail without a preceding them first with a call to NvScrncaptCleanup.
Parameters
[out]pResultA double pointer to a NvScrncaptResult object to get the allocated one
Returns
NvScrncaptStatus The completion status of the operation. Possible values are:
NVSCRNCAPT_STATUS_OK
NVSCRNCAPT_STATUS_OUT_OF_MEMORY
NVSCRNCAPT_STATUS_ERROR