Syntax
PXL_RETURN_CODE PxLGetCameraFeatures ( HANDLE hCamera, U32 featureId, CAMERA_FEATURES* pFeatureInfo, U32* pBufferSize );
Description
This function provides camera-specific information about the properties of a feature. It can, for example, be used to query if a feature is supported by the camera, and if that feature is supported, how many parameters it has and the current limits of those parameters.
It can be used to query information about either just one specific feature at a time, or all features at once. All features supported by the API can be queried, regardless of whether the camera supports the feature or not.
hCamera is the camera handle. This value is returned by PxLInitializeEx.
featureId is the ID of the specified feature, or set to FEATURE_ALL to return information on all supported features. Information is returned in the CAMERA_FEATURES structure in the pFeatureInfo buffer.
pFeatureInfo is the pointer to the buffer to be filled with the CAMERA_FEATURES structure containing the feature information. Set to NULL to return the required size of the buffer in pBufferSize.
pBuffersize is the number of bytes of memory (in the buffer) pointed to by pFeatureInfo. If pFeatureInfo is set to NULL then the required size of pFeatureInfo will be returned in pBufferSize.
Click here to review feature IDs, the CAMERA_FEATURES structure, and feature flags.
Feature IDs, CAMERA_FEATURES, and FEATURE_ALL are defined in the file PixeLINKTypes.h
Usage
Recommended method of using PxLGetCameraFeatures:
Call the function with pFeatureInfo set to NULL. The required size of the destination buffer is returned in pBuffersize.
Allocate the required number of bytes of memory to a buffer.
Call the function with pFeatureInfo pointing to the allocated buffer
.
Example
// Variables
CAMERA_FEATURES* pAllFeatures = NULL;
U32 bufferSize;
// Determine the size of memory required
PXL_RETURN_CODE rc = PxLGetCameraFeatures(hCamera, FEATURE_ALL, NULL, &bufferSize);
… Error checking
// Get memory
pAllFeatures = (PCAMERA_FEATURES) malloc (bufferSize);
… Error Checking
/* Make the request to get information for all the camera features */
rc = PxLGetCameraFeatures(hCamera, FEATURE_ALL, pFeatures, &bufferSize);
/* If no error – show feature IDs */
if (API_SUCCESS(rc))
{
for (i = 0; i < pFeatures->uNumberOfFeatures; i++)
{
printf("Feature %d = feature id %d\n", i, pAllFeatures->pFeatures[i].uFeatureId);
}
}
// When finished, clean up
free(pFeatures);
pFeatures = NULL;Comments, Restrictions and Limitations
Features are camera dependent. Use this function to identify the presence and range of all features in the camera. The returned information identifying the features can be used to qualify calls to the PxLGetFeature and PxLSetFeature functions prior to use.
When querying information for all features at once (using FEATURE_ALL), you cannot index into the CAMERA_FEATURE array using the feature id value. i.e. looking at the code sample above, you cannot get the flags for FEATURE_ROI by doing this:
U32 flags = pAllFeatures->pFeatures[i].uFlags
Rather, you must search the array for the CAMERA_FEATURE struct with the information for FEATURE_ROI.
// Search for FEATURE_ROI in the CAMERA_FEATURE array and read the flags
for(int i=0; i < pAllFeatures->uNumberOfFeatures; i++) {
if (FEATURE_ROI == pAllFeatures->pFeatures[i].uFeatureId) {
featureRoiFlags = pAllFeatures->pFeatures[i].uFlags;
}
}PxLGetCameraFeatures will report that FEATURE_LOOKUP_TABLE has only one parameter. The maximum value for this parameter is actually the number of entries in the lookup table. If that value is N, then the range of valid values for any element in the table is 0 to N-1.
Note: The syntax for the .NET version of this function, GetCameraFeatures, is as follows:
ReturnCode rc = Api.GetCameraFeatures(int cameraHandle, Feature feature, ref CameraFeature featureInformation);
This function cannot be used to return a list of all features supported by the camera, but instead can be used to return the flags and number of parameters for a feature, as well as the minimum and maximum values for those parameters. An example using GetCameraFeatures can be found in the GetCameraFeature sample application, included with the SDK.