DTWAIN_EnumBrightnessValues

The DTWAIN_EnumBrightnessValues function gets all of the possible brightness settings available for the current Source.

LONG DTWAIN_EnumBrightnessValues (

Parameters

Source

An open TWAIN Source.

lpBitDepth

Address of a DTWAIN_ARRAY (an LPDTWAIN_ARRAY) that will store the Source's brightness values, or NULL.

bExpandRange

Flag that determines whether the values will be expanded if the Source stores them in a TW_RANGE.

Return Values

The return value is the number of brightness values supported by the Source.  If there is an error, or if the Source does not support brightness values, 0 is returned.

Comments

The DTWAIN_EnumBrightnessValues function gets all of the brightness values supported by the TWAIN Source, Source.  On return, lpBrightnessVals will be filled with all of the available brightness values.  Note that your application does not send a DTWAIN_ARRAY, but an LPDTWAIN_ARRAY (a pointer to a DTWAIN_ARRAY).  The data type of the returned DTWAIN_ARRAY is DTWAIN_FLOAT.  If lpBrightnessVals is NULL or 0, no array is returned and only the number of brightness values is returned.

If the Source stores the brightness values in a range type (a DTWAIN_RANGE), then the bExpandRange argument determines whether the values will be expanded into lpBrightnessVals before returning.  If bExpandRange is TRUE, then DTWAIN_RANGE values will be expanded into a DTWAIN_ARRAY and lpBrightnessVals will be a regular DTWAIN_ARRAY.  If bExpandRange is FALSE, the range is not expanded and lpBrightnessVals will be a DTWAIN_RANGE type.

Note that bExpandRange is meaningful only if the Source uses a TW_RANGE to store the brightness values, otherwise a regular DTWAIN_ARRAY is always used.  To determine if the Source uses a range to store the brightness values, call DTWAIN_GetCapContainer(Source, DTWAIN_CV_ICAPBRIGHTNESS, DTWAIN_CAPGET)  and check for a DTWAIN_CONTRANGE return value.

Many Sources store the brightness values in terms of a range, since there could be hundreds, possibly thousands of values.  Expanding the range into array values will cause more storage to be used, slowing down DTWAIN_EnumBrightnessValues during expansion.

Note that not all Sources support brightness settings.  To determine if a Source supports brightness, call DTWAIN_IsCapSupported(Source, DTWAIN_CV_ICAPBRIGHTNESS).

Example:

#include "dtwain.h"

void foo( )

{

   DTWAIN_ARRAY EnumArray;

   LONG Count;

   DTWAIN_SOURCE Source;

   DTWAIN_FLOAT   Value;

   LONG Count2;

   LONG ContainerType;

   DTWAIN_BOOL Expand;

   /* ... */

   /* Assume Source has been opened */

   /* ... */

   /* Test if Source uses a range.  We will handle the expansion ourselves */

   Expand = TRUE;

   ContainerType = DTWAIN_GetCapContainer( Source, DTWAIN_CV_ICAPBRIGHTNESS, DTWAIN_CAPGET );

   if ( ContainerType == DTWAIN_CONTRANGE )

      Expand = FALSE;

   /* Get the actual values, no expansion if  Source uses a range */

   Count = DTWAIN_EnumBrightnessValues( Source, &EnumArray, Expand );

   if ( Count > 0 )

   {

        /* Print each brightness value */

        for (Count2 = 0; Count2 < Count; Count2++ )

        {

             if ( Expand == FALSE )

             /* This is a normal DTWAIN_ARRAY */

                DTWAIN_ArrayGetAt( EnumArray, Count2, &Value );

             else

             /* This is an unexpanded  DTWAIN_RANGE, so use DTWAIN_RANGE functions */

                  DTWAIN_RangeGetExpValue( EnumArray, Count2, &Value );

             printf( "Brightness Value %d is %lf\n", Count, Value);

       }

  }

  /* Destroy values.  Note that a DTWAIN_RANGE is a DTWAIN_ARRAY, so you can call

      any DTWAIN_ARRAY functions on a DTWAIN_RANGE */

  DTWAIN_ArrayDestroy( EnumArray );

}

TWAIN State Transitions

The Source must be in State 4 or higher

Prerequisite Function Call(s)

DTWAIN_SysInitialize

DTWAIN Source Selection Function

See Also

Setting / Getting Brightness Values