/*
 * STRUCT: SE_DESIRED_IMAGE_PARAMETERS
 *
 *    Parameters to repack/convert an <Image> using the
 *    SE_GetRearrangedImageData() or SE_RearrangeImageData() functions.
 */

Field Notes

desired_color_model

 color model (RGB, CMY, or HSV) in which the data should be returned

desired_image_signature

 Usually, the same image signature as the <Image>.  However, in some
 cases, certain 'down-sampling' or 'up-sampling' is allowed.
     Specifically, from a:
       - SE_IMAGE_SIGNATURE_LUMINANCE_AND_ALPHA <Image>,
         you can ask for
           - SE_IMAGE_SIGNATURE_ALPHA,
           - SE_IMAGE_SIGNATURE_LUMINANCE, or
           - SE_IMAGE_SIGNATURE_LUMINANCE_AND_ALPHA.
       - SE_IMAGE_SIGNATURE_123COLOR <Image>, you can ask for
           - SE_IMAGE_SIGNATURE_FIRST_COLOR_COORD,
           - SE_IMAGE_SIGNATURE_SECOND_COLOR_COORD, or
           - SE_IMAGE_SIGNATURE_THIRD_COLOR_COORD.
           - SE_IMAGE_SIGNATURE_123COLOR_ALPHA
       - SE_IMAGE_SIGNATURE_123COLOR_ALPHA <Image>, you can ask for
           - SE_IMAGE_SIGNATURE_FIRST_COLOR_COORD,
           - SE_IMAGE_SIGNATURE_SECOND_COLOR_COORD,
           - SE_IMAGE_SIGNATURE_THIRD_COLOR_COORD, or
           - SE_IMAGE_SIGNATURE_ALPHA.

   The desired image signature takes precedence over the numerous
   desired_bits_of_xxxx fields, listed later in this struct.

   The value of desired_image_signature defines which of the
   desired_bits_of_xxxx fields will be examined and which
   will be ignored.

 For example, if desired_image_signature == SE_IMAGE_SIGNATURE_ALPHA,
 then the desired_bits_of_alpha field will be used appropriately,
 and all of the other desired_bits_of_xxxx fields will be ignored.

desired_scan_direction

 the way the texels should be ordered in 2 dimensions for the data
 which is returned

desired_scan_direction_z

 the way the texels should //      be ordered in the third dimension
 for the data which is returned (ignored for 2-dimensional <Images>)

desired_component_type

 specifies the form each converted component value should take - an
 unsigned integer, a signed integer, or a floating point value. Note
 that for unsigned or signed integers, the maximum number of bits
 currently allowed is 32. For floats, the only choices are 32 and
 64 bits.

 Converting from a floating point value to a signed integer will
 first clamp the floating point value to be between -1.0 and 1.0,
 then scale the resulting value between the minimum and maximum
 range of the signed integer.

 Converting from a signed integer value to a floating point value
 will create a floating point value between -1.0 and 1.0

 No checking is done on conversions from 32 to 64 bit floats
 (or vice-versa)

 For unsigned to signed conversions, see ignore_negative_values
 field.

ignore_negative_values

 concerns conversions from signed integer or floating point to an unsigned
 integer (and vice-versa)

      If the source number is a floating point number, then it is
      clamped to a value between -1.0 and 1.0, before it is
      converted to an integer.

      If ignore_negative_values == SE_TRUE:

         Converting from an SE_SIGNED_INTEGER or SE_FLOATING_POINT
                      to an SE_UNSIGNED_INTEGER


              Source Value between             |       Result Value
          -------------------------------------+-----------------------------
          [max. negative source value and 0]   |   set to  0
                                               |
          (0 and max. positive source value]   |   scaled between 0 and
                                               |   max. positive result value


       Converting from an SE_UNSIGNED_INTEGER
                    to an SE_SIGNED_INTEGER or SE_FLOATING_POINT

              Source Value between             |       Result Value
          -------------------------------------+-----------------------------
          [0 and max. positive source value]   |   scaled between 0 and
                                               |   max. positive result value


    If ignore_negative_values == SE_FALSE:

       Converting from an SE_SIGNED_INTEGER or SE_FLOATING_POINT
                    to an SE_UNSIGNED_INTEGER

              Source Value                     |       Result Value
          -------------------------------------+-----------------------------
              max. negative source value       |            0
                                               |
                     0                         |   middle of result range
                                               |
              max. positive source value       |   max. positive result value

          and all other values are scaled between the given mappings.


       Converting from an SE_UNSIGNED_INTEGER
                    to an SE_SIGNED_INTEGER or SE_FLOATING_POINT

              Source Value                     |       Result Value
          -------------------------------------+-----------------------------
                     0                         |   max. negative result value
                                               |
            middle of source range             |            0
                                               |
            max. positive source value         |   max. positive result value

          and all other values are scaled in between.

make_values_little_endian

 the individual component values will
      be returned as:
         big    endian values if make_values_little_endian == SE_FALSE
         little endian values if make_values_little_endian == SE_TRUE

desired_bits_of_alpha

 the number of bits desired per alpha value.
      If 0, then no alpha values will be returned. If the source image
      is SE_IMAGE_SIGNATURE_123COLOR and the desired_image_signature
      is SE_IMAGE_SIGNATURE_123COLOR_ALPHA, then the default value for
      the alpha component is the maximum for the component type.

desired_bits_of_luminance

 the number of bits desired per
      luminance value. If 0, then no luminance values will be returned.

desired_bits_of_first_color_coord

 the number of bits desired for
      the first color coordinate of a texel (Red, Cyan, or Hue, based
      on the value of desired_color_model). If 0, then the first color
      coordinate of a texel is not returned.

desired_bits_of_second_color_coord

 the number of bits desired
      for the second color coordinate of a texel (Green, Magenta, or
      Saturation, based on value of desired_color_model). If 0, then
      the second color coordinate of a texel is not returned.

desired_bits_of_third_color_coord

 the number of bits desired
      for the first color coordinate of a texel (Blue, Yellow, or
      Value, based on the value of desired_color_model). If 0, then
      the third color coordinate of a texel is not returned.

desired_bits_of_bump

 the number of bits desired per bump value.
      If 0, then no bump values will be returned.

desired_bits_of_material1

 the number of bits desired per
     material1 value. If 0, then no material1 values will
     be returned.

desired_bits_of_material2

 the number of bits desired per
     material2 value. If 0, then no material2 values will
     be returned.

desired_bits_of_material2_percentage

 the number of bits
     per material2_percentage value. If 0, then no values will
     be returned for material2_percentage.

desired_bits_of_material3

 the number of bits desired per
     material3 value. If 0, then no material3 values will
     be returned.

desired_bits_of_material3_percentage

 the number of bits
     per material3_percentage value. If 0, then no values will
     be returned for material3_percentage.

desired_bits_of_image_id

 the number of bits desired per
     image ID value. If 0, then no image ID values will
     be returned.