DTWAIN_EnumContrastValues

The DTWAIN_EnumContrastValues function gets all of the possible contrast settings for a Source.

LONG DTWAIN_EnumContrastValues (

Parameters

Source

An open TWAIN Source.

lpBitDepth

Address of a DTWAIN_ARRAY (an LPDTWAIN_ARRAY) that will store the Source's contrast 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 contrast values supported by the Source.  If there is an error, or if the Source does not support contrast values, 0 is returned.

Comments

The DTWAIN_EnumContrastValues function gets all of the contrast values supported by the TWAIN Source, Source.  On return, lpContrastVals will be filled with all of the available contrast 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 lpContrastVals is NULL or 0, no array is returned and only the number of contrast values is returned.

If the Source stores the contrast values in a range type (a DTWAIN_RANGE), then the bExpandRange argument determines whether the values will be expanded into lpContrastVals before returning.  If bExpandRange is TRUE, then DTWAIN_RANGE values will be expanded into a DTWAIN_ARRAY and lpContrastVals will be a regular DTWAIN_ARRAY.  If bExpandRange is FALSE, the range is not expanded and lpContrastVals will be a DTWAIN_RANGE type.  Note that bExpandRange is meaningful only if the Source uses a TW_RANGE to store the contrast values, otherwise a regular DTWAIN_ARRAY is always used.  To determine if the Source uses a range to store the contrast values, call DTWAIN_GetCapContainer(Source, DTWAIN_CV_ICAPCONTRAST, DTWAIN_CAPGET)  and check for a DTWAIN_CONTRANGE return value.

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

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

Example:

#include "dtwain.h"

void SomeCode( )

{

   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_ICAPCONTRAST, DTWAIN_CAPGET );

   if ( ContainerType == DTWAIN_CONTRANGE )

      Expand = FALSE;

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

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

   if ( Count > 0 )

   {

        /* Print each contrast 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( "Contrast 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 Contrast Values