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

Field Notes

colour_model

 colour model in which the data shall be returned

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_IMG_SIG_LUMINANCE_AND_ALPHA <Image>,
         you can ask for
           - SE_IMG_SIG_ALPHA,
           - SE_IMG_SIG_LUMINANCE, or
           - SE_IMG_SIG_LUMINANCE_AND_ALPHA.
       - SE_IMG_SIG_123COLOUR <Image>, you can ask for
           - SE_IMG_SIG_COLOUR_COORDINATE_1,
           - SE_IMG_SIG_COLOUR_COORDINATE_2, or
           - SE_IMG_SIG_COLOUR_COORDINATE_3.
           - SE_IMG_SIG_123COLOUR_ALPHA
       - SE_IMG_SIG_123COLOUR_ALPHA <Image>, you can ask for
           - SE_IMG_SIG_COLOUR_COORDINATE_1,
           - SE_IMG_SIG_COLOUR_COORDINATE_2,
           - SE_IMG_SIG_COLOUR_COORDINATE_3, or
           - SE_IMG_SIG_ALPHA.

   The desired image signature takes precedence over the numerous
   desired bits_of_xxxx fields, listed later in this struct; it
   defines which of the desired bits_of_xxxx fields will be
   examined and which will be ignored.

   For example, if image_signature == SE_IMG_SIG_ALPHA,
   then the desired bits_of_alpha field will be used appropriately,
   and all the other desired bits_of_xxxx fields will be ignored.

scan_direction

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

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>)

component_data_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_IMG_COMP_TYP_SIGNED_INTEGER or
                       SE_IMG_COMP_TYP_FLOATING_POINT
               to an SE_IMG_COMP_TYP_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_IMG_COMP_TYP_UNSIGNED_INTEGER
               to an SE_IMG_COMP_TYP_SIGNED_INTEGER or
                     SE_IMG_COMP_TYP_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_IMG_COMP_TYP_SIGNED_INTEGER or
                     SE_IMG_COMP_TYP_FLOATING_POINT
               to an SE_IMG_COMP_TYP_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_IMG_COMP_TYP_UNSIGNED_INTEGER
               to an SE_IMG_COMP_TYP_SIGNED_INTEGER or
                     SE_IMG_COMP_TYP_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

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_IMG_SIG_123COLOUR and the desired image_signature
 is SE_IMG_SIG_123COLOUR_ALPHA, then the default value for
 the alpha component is the maximum for the component type.

bits_of_luminance

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

bits_of_colour_coordinate_1

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

bits_of_colour_coordinate_2

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

bits_of_colour_coordinate_3

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

bits_of_bump_map_height

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

bits_of_material_1

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

bits_of_material_2

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

bits_of_material_3

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

bits_of_material_2_percentage

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

bits_of_material_3_percentage

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

bits_of_image_index

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

bits_of_bump_map_u

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

bits_of_bump_map_v

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