Syntax

 

PXL_RETURN_CODE PxLGetFeature (

HANDLE  hCamera,

U32     featureId,

U32*    pFlags,

U32*    pNumParams,

float*  pParams );

 

Description


This function returns the current value of the selected feature.  Features are camera-dependent.


  • hCamera is the camera handle.  This value is returned by PxLInitializeEx.

  • featureId is the ID of the selected feature.  Features and feature IDs are defined in the file PixeLINKTypes.h.

  • pFlags is the pointer to the current flag for the feature.  Feature flags are defined in the file PixeLINKTypes.h.

  • pNumParams is the pointer to the number of entries in the pParams array.  If pParams is set to NULL then the required number of array entries will be returned in pNumParams.

  • pParams is the pointer to an array of values that to be filled with the current parameters for the specified feature.  Set to NULL to return the required number of array entries in pNumberParams.


Usage


Recommended method of using PxLGetFeature:


  • Call the function with pParams set to NULL.  If the return code indicates success, the required number of array entries is returned in the U32 pointed to by pNumParams.

  • Allocate the required number of bytes of memory to hold the parameters, that is, *pNumParams × sizeof(float).  

  • Call the function with pFlags and pParams set to point to their own areas of allocated memory.


Example


// Variables

U32     numParams = 0;

U32     featureId = FEATURE_GAIN;  // Set to the desired feature. e.g. FEATURE_GAIN

U32     flags = 0;

float*  pParameters = NULL;

PXL_RETURN_CODE rc;

 
// Determine the number of parameters required

rc = PxLGetFeature(hCamera, featureId, &flags, &numParams, NULL);
 

… Error checking
 

// NOTE: flags has an unknown value at this point. It has not been set by the API.


// Allocate memory

pParameters = (float*)malloc( numParams * sizeof(float) );

 
… Error Checking

 
/* Make the request */

rc = PxLGetFeature(hCamera, featureId, &flags, &numParams, pParameters); 

// If no error, print parameter values

if (API_SUCCESS(rc))

{

  for (U32 i = 0; i < numParams; i++) 

    {

    printf("Parameter %d = %f\n", i, pParameters[i]);

  }
 
  // Can now examine flags here for more information

}

 
// When finished

free(pParameters);

pParameters = NULL;

 

dotNET Example


int numParms = 0;

FeatureFlags flags = 0;

ReturnCode rc;


// Determine the number of parameters for the feature

rc = Api.GetFeature(hCamera, Feature.Roi, ref flags, ref numParms, null);


// Create an array for the parameter values

float[] parms = new float[numParms];


// Make the request

rc = Api.GetFeature(hCamera, Feature.Roi, ref flags, ref numParms, parms);


// If no error, print the parameter values

if(Api.IsSuccess(rc)) {

    for(int i=0; i< numParms; i++) {
  
        Console.WriteLine(System.Convert.ToString(parms[i]);

  }
}


Comments, Restrictions and Limitations


Features


Features are camera dependent.  The PxLGetCameraFeatures function should be used to identify the presence and range of all features present in the camera.The pParm parameter is listed as IN OUT, but for almost all features it is really an OUT parameter only.  Currently, the only exception is FEATURE_GPIO.  When using PxLGetFeature to retrieve the state of one of the GPOs, you must fill in the value of the first parameter – the GPO Number parameter – with a valid GPO number.


Flags


When querying for the number of parameters (by passing in a pParms of NULL), the flags are NOT set. The flags value should be examined only after successfully reading the feature's parameters.


Using PxLGetFeature with descriptors


PxLGetFeature can read the settings of any custom descriptors that are in use.  Custom descriptors are managed using the advanced functions.  Note that if all descriptors are in focus at once (rather than just a single descriptor), calling PxLGetFeature will generate an error.