fastuidraw_atlas_image_fetch.glsl.hpp

Go to the documentation of this file.

/*!
 * \file fastuidraw_atlas_image_fetch.glsl.hpp
 * \brief file fastuidraw_atlas_image_fetch.glsl.hpp
 *
 * Copyright 2018 by Intel.
 *
 * Contact: kevin.rogovin@gmail.com
 *
 * This Source Code Form is subject to the
 * terms of the Mozilla Public License, v. 2.0.
 * If a copy of the MPL was not distributed with
 * this file, You can obtain one at
 * http://mozilla.org/MPL/2.0/.
 *
 * \author Kevin Rogovin <kevin.rogovin@gmail.com>
 *
 */

/*!\addtogroup GLSLVertFragCode
 * @{
 */

#ifndef FASTUIDRAW_IMAGE_ATLAS_DISABLED

#ifdef GLSL_DOXYGEN
/*!
 * \def FASTUIDRAW_IMAGE_ATLAS_DISABLED
 * If FASTUIDRAW_IMAGE_ATLAS_DISABLED is defined by the GLSL preamble
 * generated by fastuidraw, then images backed by an atlas (i.e. \ref
 * fastuidraw::Image::type() is \ref fastuidraw::Image::on_atlas) do
 * not occur and are not supported.
 */
#define FASTUIDRAW_IMAGE_ATLAS_DISABLED

/*!
 * \def FASTUIDRAW_IMAGE_ATLAS_COLOR_TILE_SIZE
 * The size of the color tiles (as an uint), i.e. \ref fastuidraw::ImageAtlas::color_tile_size().
 * Value is always a power of 2.
 */
#define FASTUIDRAW_IMAGE_ATLAS_COLOR_TILE_SIZE

/*!
 * \def FASTUIDRAW_IMAGE_ATLAS_COLOR_TILE_RECIP_SIZE
 * The reciprocal of size of the color tiles (as a float).
 * Value is always a power of 2.
 */
#define FASTUIDRAW_IMAGE_ATLAS_COLOR_TILE_RECIP_SIZE

/*!
 * \def FASTUIDRAW_IMAGE_ATLAS_COLOR_TILE_LOG2_SIZE
 * The log2 of size of the color tiles (as an uint).
 */
#define FASTUIDRAW_IMAGE_ATLAS_COLOR_TILE_LOG2_SIZE

/*!
 * \def FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_SIZE
 * The size of the index tiles, i.e. \ref fastuidraw::ImageAtlas::index_tile_size().
 * Value is always a power of 2.
 */
#define FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_SIZE

/*!
 * \def FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_RECIP_SIZE
 * The reciprocal of size of the index tiles (as a float)
 */
#define FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_RECIP_SIZE

/*!
 * \def FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_LOG2_SIZE
 * The log2 of size of the index tiles (as an uint).
 */
#define FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_LOG2_SIZE

#endif

/*!
 * \brief
 * Structure that describes the relationship between
 * the master index tile and the color tiles of an image.
 * Only available if \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is
 * not defined.
 */
struct fastuidraw_image_info_type
{
  /*! Number of index tile levels */
  uint num_levels;

  /*!
   * The amount to delta on the master index tile
   * to move one texel in the color tile.
   */
  float image_texel_size_on_master_index_tile;

  /*!
   * The reciprocial of \ref
   * image_texel_size_on_master_index_tile
   */
  float recip_image_texel_size_on_master_index_tile;
};

/*!
 * \brief
 * Structure that fully describes a \ref
 * fastuidraw::Image or a sub-image of one.
 * Only available if \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is
 * not defined.
 */
struct fastuidraw_image_extended_info_type
{
  /*!
   * GLSL style inheritance
   */
  fastuidraw_image_info_type base;

  /*! the size of the image in texels */
  vec2 image_size;

  /*!
   * the bottom-left corner of the master index tile
   * of the sub-rectangle of the Image being examined
   */
  vec2 master_index_tile_bottom_left;

  /*! the layer of the master index tile */
  uint master_index_tile_layer;
};

/*!
 * \brief
 * Structure to give information about what tile and where
 * within a tile an image texel is located.
 * Only available if \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is
 * not defined.
 */
struct fastuidraw_compute_image_atlas_coord_type
{
  /*!
   * the most positive value allowed to go in texels
   * before leaving the tile
   */
  vec2 max_delta_within_tile;

  /*! the unnormalized texel coordinate within the color-atlas */
  vec2 unnormalized_texcoord_xy;

  /*! the layer within the color atlas */
  uint layer;
};

/*!
 * \brief
 * Structure that holds the 2x2 texel block.
 * Only available if \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is
 * not defined.
 */
struct fastuidraw_image_texture_gather_output_type
{
  /*!
   * The texel value in the (min-x, min-y) corner of the
   * 2x2 texel block
   */
  vec4 c00;

  /*!
   * The texel value in the (max-x, min-y) corner of the
   * 2x2 texel block
   */
  vec4 c10;

  /*!
   * The texel value in the (min-x, max-y) corner of the
   * 2x2 texel block
   */
  vec4 c01;

  /*!
   * The texel value in the (max-x, max-y) corner of the
   * 2x2 texel block
   */
  vec4 c11;

  /*!
   * The atlas coordinate for the (min-x, min-y) corner
   */
  fastuidraw_compute_image_atlas_coord_type atlas_location_t00;
};

/*!
 * Given the number of levels of an \ref fastuidraw::Image with
 * \ref fastuidraw::Image::type() being \ref fastuidraw::Image::on_atlas,
 * compute the \ref fastuidraw_image_info_type. Only available if
 * \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is not defined.
 * \param num_levels value of \ref fastuidraw::Image::number_index_lookups()
 * \param d location to which to write the results
 */
void
fastuidraw_compute_image_info(in uint num_levels, out fastuidraw_image_info_type d)
{
  d.num_levels = num_levels;
  if (num_levels >= 1u)
    {
      /* Each level increases the size by a factor of FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_SIZE,
       * thus the ratio is R where R is given by
       *
       *  R = C * pow(FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_SIZE, num_levels - 1)
       *
       * where
       *
       *  C = FASTUIDRAW_IMAGE_ATLAS_COLOR_TILE_SIZE
       *
       * Now,
       *
       *  R = C * pow(FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_SIZE, num_levels - 1)
       *    = C * pow(2, FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_LOG2_SIZE * (num_levels - 1))
       *
       * Using bitshift, we then have:
       *
       *  R = C * (1u << (FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_LOG2_SIZE * (num_levels - 1)))
       */
      uint ww = uint(FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_LOG2_SIZE) * (num_levels - 1u);
      float index_pows = float(1u << ww);

      d.recip_image_texel_size_on_master_index_tile = float(FASTUIDRAW_IMAGE_ATLAS_COLOR_TILE_SIZE) * index_pows;
      d.image_texel_size_on_master_index_tile = 1.0 / d.recip_image_texel_size_on_master_index_tile;
    }
  else
    {
      d.image_texel_size_on_master_index_tile = 1.0;
      d.recip_image_texel_size_on_master_index_tile = 1.0;
    }
}

/*!
 * Given a master_tile_tex_coord value, compute the image coordinate
 * relate to the actual fastuidraw::Image (not a sub-image as tracked
 * by fastuidraw_image_extended_info_type additional fields). Only
 * available if \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is not defined.
 * \param master_tile_tex_coord interpolated value of \ref fastuidraw::Image::master_index_tile().xy
 * \param image_info infomration of the image
 */
vec2
fastuidraw_compute_root_image_coordinate(in vec2 master_tile_tex_coord,
                                         in fastuidraw_image_info_type image_info)
{
  /* The master index tile of an Image is ALWAYS starts at a multiple
   * of FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_SIZE, so the value of
   * mod(master_tile_tex_coord, FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_SIZE)
   * gives the relative coordinate within the tile. To avoid the
   * expensive divide, we use FASTUIDRAW_IMAGE_ATLAS_INDEX_RECIP_TILE_SIZE
   * together with floor.
   */
  vec2 relative;

  relative = master_tile_tex_coord
    - vec2(FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_SIZE) * floor(FASTUIDRAW_IMAGE_ATLAS_INDEX_RECIP_TILE_SIZE * master_tile_tex_coord);

  /* The image coordinate is then given by the relative value times
   * the size ratio of the color-tile to master-tile
   */
  return relative * image_info.recip_image_texel_size_on_master_index_tile;
}

/*!
 * Gives the signed distance from an image coordinate value to
 * the tile boundary. NOTE! the input value is the image coordinate
 * within a fastuidraw::Image, not a sub-image.
 * \param root_image_coordinate texel coordinate within a fastuidraw::Image;
 *                              an image coordinate within a partial image
 *                              is not useful.
 * \param[out] tile_min_dist signed distance, in image texels, to min-side of tile
 * \param[out] tile_max_dist signed distance, in image texels, to max-side of tile
 */
void
fastuidraw_image_atlas_compute_tile_range(in float root_image_coordinate,
                                          out float tile_min_dist,
                                          out float tile_max_dist)
{
  float tile_coord;

  tile_coord = root_image_coordinate
    - float(FASTUIDRAW_IMAGE_ATLAS_COLOR_TILE_SIZE) * floor(root_image_coordinate * FASTUIDRAW_IMAGE_ATLAS_COLOR_RECIP_TILE_SIZE);

  tile_min_dist = -tile_coord;
  tile_max_dist = float(FASTUIDRAW_IMAGE_ATLAS_COLOR_TILE_SIZE) - 1.0 - tile_coord;
}

/*!
 * Gives the signed distance from an image coordinate value to
 * the tile boundary. NOTE! the input value is the image coordinate
 * within a fastuidraw::Image, not a sub-image. Only available
 * if \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is not defined.
 * \param root_image_coord texel coordinate within a fastuidraw::Image;
 *                         an image coordinate within a partial image
 *                         is not useful.
 * \param[out] tile_min_dist signed distance, in image texels, to min-side of tile
 * \param[out] tile_max_dist signed distance, in image texels, to max-side of tile
 */
void
fastuidraw_image_atlas_compute_tile_range(in vec2 root_image_coord,
                                          out vec2 tile_min_dist,
                                          out vec2 tile_max_dist)
{
  fastuidraw_image_atlas_compute_tile_range(root_image_coord.x, tile_min_dist.x, tile_max_dist.x);
  fastuidraw_image_atlas_compute_tile_range(root_image_coord.y, tile_min_dist.y, tile_max_dist.y);
}

/*!
 * Computes the sub-image-texel coordinate from a master-tile texel coordinate. Only
 * available if \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is not defined.
 * \param master_tile_tex_coord interpolated value of \ref fastuidraw::Image::master_index_tile().xy
 * \param image_info information of the image
 */
vec2
fastuidraw_compute_image_coordinate(in vec2 master_tile_tex_coord,
                                    in fastuidraw_image_extended_info_type image_info)
{
  vec2 return_value;

  return_value = (master_tile_tex_coord - image_info.master_index_tile_bottom_left)
    * image_info.base.recip_image_texel_size_on_master_index_tile;

  return return_value;
}

/*!
 * Computes the the master-tile texel coordinate from a sub-image-texel coordinate. Only
 * available if \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is not defined.
 * \param image_coordinate texel coordinate relative to the sub-image described by image_info
 * \param image_info information of the image
 */
vec2
fastuidraw_compute_master_index_tile_coordinate(in vec2 image_coordinate,
                                                in fastuidraw_image_extended_info_type image_info)
{
  vec2 return_value;

  return_value = image_coordinate * image_info.base.image_texel_size_on_master_index_tile
    +  image_info.master_index_tile_bottom_left;

  return return_value;
}

/*!
 * Clamps a image texel coordinate for nearest filtering. Only
 * available if \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is not defined.
 * \param image_coordinate texel coordinate relative to the sub-image described by image_info
 * \param image_info information of the image
 */
vec2
fastuidraw_image_coordinate_clamp_for_nearest_filtering(in vec2 image_coordinate,
                                                        in fastuidraw_image_extended_info_type image_info)
{
  return clamp(image_coordinate, vec2(0.0), image_info.image_size);
}

/*!
 * Clamps a image texel coordinate for linear filtering. Only
 * available if \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is not defined.
 * \param image_coordinate texel coordinate relative to the sub-image described by image_info
 * \param image_info information of the image
 * \param pow2_lod pow2 of lod parameter
 */
vec2
fastuidraw_image_coordinate_clamp_for_linear_filtering(in vec2 image_coordinate,
                                                       in fastuidraw_image_extended_info_type image_info,
                                                       float pow2_lod)
{
  return clamp(image_coordinate,
               vec2(0.5 * pow2_lod),
               image_info.image_size - vec2(0.5 * pow2_lod));
}

/*!
 * Clamps a image texel coordinate for cubic filtering. Only
 * available if \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is not defined.
 * \param image_coordinate texel coordinate relative to the sub-image described by image_info
 * \param image_info information of the image
 */
vec2
fastuidraw_image_coordinate_clamp_for_cubic_filtering(in vec2 image_coordinate,
                                                      in fastuidraw_image_extended_info_type image_info)
{
  return clamp(image_coordinate,
               vec2(2.0),
               image_info.image_size - vec2(2.0));
}

///@cond

/* Structure to make fastuidraw_compute_image_atlas_coord_helper()
 * less ugly
 */
struct fastuidraw_compute_image_atlas_coord_helper_type
{
  vec2 master_tile_texel_coord;
  uint index_layer;
  uvec4 tile_id;
};

void
fastuidraw_compute_image_atlas_coord_helper_init(in vec2 master_tile_texel_coord,
                                                 in uint index_layer,
                                                 out fastuidraw_compute_image_atlas_coord_helper_type v)
{
  v.master_tile_texel_coord = master_tile_texel_coord;
  v.index_layer = index_layer;
  v.tile_id = texelFetch(fastuidraw_imageIndexAtlas,
                         ivec3(v.master_tile_texel_coord, v.index_layer),
                         0);
  v.index_layer = v.tile_id.z + 256u * v.tile_id.w;
}

void
fastuidraw_compute_image_atlas_coord_helper_iterate(inout fastuidraw_compute_image_atlas_coord_helper_type v)
{
  vec2 index_tile_offset;
  vec2 texel_coordinate;

  v.master_tile_texel_coord -= floor(v.master_tile_texel_coord);
  index_tile_offset = v.master_tile_texel_coord * float(FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_SIZE);
  texel_coordinate = index_tile_offset
    + vec2(v.tile_id.xy) * float(FASTUIDRAW_IMAGE_ATLAS_INDEX_TILE_SIZE);

  v.tile_id = texelFetch(fastuidraw_imageIndexAtlas,
                         ivec3(texel_coordinate, v.index_layer),
                         0);
  v.index_layer = v.tile_id.z + 256u * v.tile_id.w;
  v.master_tile_texel_coord = texel_coordinate;
}

void
fastuidraw_compute_image_atlas_coord_helper_fini(in fastuidraw_compute_image_atlas_coord_helper_type v,
                                                 out fastuidraw_compute_image_atlas_coord_type return_value)
{

  /* at this point index_layer gives the layer into colorAtlas
   * and tile_id gives which tile in the color atlas
   */
  vec2 tile_offset;
  uint subtile_image_size;

  subtile_image_size = uint(FASTUIDRAW_IMAGE_ATLAS_COLOR_TILE_SIZE);
  tile_offset = (v.master_tile_texel_coord - floor(v.master_tile_texel_coord)) * float(subtile_image_size);

  return_value.unnormalized_texcoord_xy = tile_offset //offset into tile
    + vec2(v.tile_id.xy) * float(FASTUIDRAW_IMAGE_ATLAS_COLOR_TILE_SIZE); //location of tile

  return_value.max_delta_within_tile =
    vec2(float(FASTUIDRAW_IMAGE_ATLAS_COLOR_TILE_SIZE - 1u)) - tile_offset;

  return_value.layer = v.index_layer;
}
///@endcond

/*!
 * Computes the image-atlas coordinate. Only available if \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED
 * is not defined.
 * \param master_tile_texel_coord unnormalized texel coordinate of within the master-index tile
 * \param index_layer what layer from the index-atlas the master tile is located at
 * \param num_levels number of index levels needed to reach the color-tile
 * \param return_value location to which to write values
 */
void
fastuidraw_compute_image_atlas_coord(in vec2 master_tile_texel_coord,
                                     in uint index_layer,
                                     in uint num_levels,
                                     out fastuidraw_compute_image_atlas_coord_type return_value)
{
  fastuidraw_compute_image_atlas_coord_helper_type v;

  fastuidraw_compute_image_atlas_coord_helper_init(master_tile_texel_coord, index_layer, v);
  for(uint i = 1u; i < num_levels; ++i)
    {
      fastuidraw_compute_image_atlas_coord_helper_iterate(v);
    }
  fastuidraw_compute_image_atlas_coord_helper_fini(v, return_value);
}

/*!
 * Computes the image-atlas coordinate. Only available if \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED
 * is not defined.
 * \param image_texel_coordinate image texel coordinate relative to the sub-image described by image_info
 * \param image_info information of the image
 * \param return_value location to which to write values
 */
void
fastuidraw_compute_image_atlas_coord(in vec2 image_texel_coordinate,
                                     in fastuidraw_image_extended_info_type image_info,
                                     out fastuidraw_compute_image_atlas_coord_type return_value)
{
  vec2 master_tile_texel_coord;

  master_tile_texel_coord = fastuidraw_compute_master_index_tile_coordinate(image_texel_coordinate, image_info);
  fastuidraw_compute_image_atlas_coord(master_tile_texel_coord,
                                       image_info.master_index_tile_layer,
                                       image_info.base.num_levels,
                                       return_value);
}

///@cond
void
fastuidraw_atlas_image_gather(in int lod_i,
                              in float lod_factor,
                              in float inverse_lod_factor,
                              in vec2 master_tile_texel_coord,
                              in uint index_layer,
                              in fastuidraw_image_info_type image_info,
                              out fastuidraw_image_texture_gather_output_type output_value)
{
  /* Sighs, we need to do the bilinear filter ourselves because
   * atleas one of the neighboring texels is in a different tile.
   */
  ivec3 t00, t10, t01, t11;
  float next_pixel_delta, half_next_pixel_delta;
  vec2 delta;

  next_pixel_delta = lod_factor * image_info.image_texel_size_on_master_index_tile;
  half_next_pixel_delta = 0.5 * next_pixel_delta;

  /* we want the texel that is half a pixel to the left/down
   * of the input location.
   */
  delta = -vec2(half_next_pixel_delta);
  fastuidraw_compute_image_atlas_coord(master_tile_texel_coord + delta,
                                       index_layer,
                                       image_info.num_levels,
                                       output_value.atlas_location_t00);

  t00 = ivec3(output_value.atlas_location_t00.unnormalized_texcoord_xy * inverse_lod_factor,
              output_value.atlas_location_t00.layer);
  if (output_value.atlas_location_t00.max_delta_within_tile.x >= lod_factor)
    {
      t10.yz = t00.yz;
      t10.x = t00.x + 1;
    }
  else
    {
      fastuidraw_compute_image_atlas_coord_type atlas_location_t10;
      vec2 delta_nxt;
      vec2 master_tile_texel_coord_nxt;

      delta_nxt = vec2(half_next_pixel_delta, -half_next_pixel_delta);
      master_tile_texel_coord_nxt = master_tile_texel_coord + delta_nxt;
      fastuidraw_compute_image_atlas_coord(master_tile_texel_coord_nxt, index_layer,
                                           image_info.num_levels, atlas_location_t10);
      t10 = ivec3(atlas_location_t10.unnormalized_texcoord_xy * inverse_lod_factor,
                  atlas_location_t10.layer);
    }

  if (output_value.atlas_location_t00.max_delta_within_tile.y >= lod_factor)
    {
      t01.xz = t00.xz;
      t01.y = t00.y + 1;

      t11.xz = t10.xz;
      t11.y = t10.y + 1;
    }
  else
    {
      fastuidraw_compute_image_atlas_coord_type atlas_location_t01;
      vec2 delta_nxt;
      vec2 master_tile_texel_coord_nxt;

      delta_nxt = vec2(-half_next_pixel_delta, half_next_pixel_delta);
      master_tile_texel_coord_nxt = master_tile_texel_coord + delta_nxt;

      fastuidraw_compute_image_atlas_coord(master_tile_texel_coord_nxt,
                                           index_layer, image_info.num_levels,
                                           atlas_location_t01);
      t01 = ivec3(atlas_location_t01.unnormalized_texcoord_xy * inverse_lod_factor,
                  atlas_location_t01.layer);

      if (output_value.atlas_location_t00.max_delta_within_tile.x >= lod_factor)
        {
          t11.x = t01.x + 1;
          t11.yz = t01.yz;
        }
      else
        {
          fastuidraw_compute_image_atlas_coord_type atlas_location_t11;
          vec2 delta_nxt;
          vec2 master_tile_texel_coord_nxt;

          delta_nxt = vec2(half_next_pixel_delta);
          master_tile_texel_coord_nxt = master_tile_texel_coord + delta_nxt;

          fastuidraw_compute_image_atlas_coord(master_tile_texel_coord_nxt,
                                               index_layer, image_info.num_levels,
                                               atlas_location_t11);
          t11 = ivec3(atlas_location_t11.unnormalized_texcoord_xy * inverse_lod_factor,
                      atlas_location_t11.layer);
        }
    }

  output_value.c00 = texelFetch(fastuidraw_imageAtlasLinear, t00, lod_i);
  output_value.c01 = texelFetch(fastuidraw_imageAtlasLinear, t01, lod_i);
  output_value.c10 = texelFetch(fastuidraw_imageAtlasLinear, t10, lod_i);
  output_value.c11 = texelFetch(fastuidraw_imageAtlasLinear, t11, lod_i);
}
///@endcond

/*!
 * Perform nearest filtering sampling on a sub-image
 * \param image_texel_coordinate image texel coordinate relative to the sub-image described by image_info
 * \param image_info information of the image
 * \param lod mipmap-lod (i.e. same value as one would feed textureLod)
 */
vec4
fastuidraw_nearest_filter_atlas_image(in vec2 image_texel_coordinate,
                                      in fastuidraw_image_extended_info_type image_info,
                                      in float lod)
{
  fastuidraw_compute_image_atlas_coord_type atlas_location;

  image_texel_coordinate = fastuidraw_image_coordinate_clamp_for_nearest_filtering(image_texel_coordinate, image_info);
  fastuidraw_compute_image_atlas_coord(image_texel_coordinate, image_info, atlas_location);

  return textureLod(fastuidraw_imageAtlasNearest,
                    vec3(atlas_location.unnormalized_texcoord_xy * fastuidraw_imageAtlasLinear_size_reciprocal,
                         atlas_location.layer),
                    lod);
}

/*!
 * Perform linear filtering sampling on a sub-image. Only available if
 * \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is not defined.
 * \param master_tile_texel_coord unnormalized texel coordinate of within the master-index tile
 * \param index_layer what layer from the index-atlas the master tile is located at
 * \param image_info information of image
 * \param lod_i which mipmap level to take (level = 0 is the base image)
 * \param lod_factor the value of pow2(lod_i)
 */
vec4
fastuidraw_linear_filter_atlas_image(in vec2 master_tile_texel_coord,
                                     in uint index_layer,
                                     in fastuidraw_image_info_type image_info,
                                     in int lod_i,
                                     in float lod_factor)
{
  vec4 image_color;
  vec2 image_coordinate, min_tile_dist, max_tile_dist;
  float slack_requirement;

  /* In exact artithmatic the texel image coordinate
   * needs to be half a texel away from the boundary
   * in each dimension to let the sampler perform the
   * bilinear filtering. Because of round-off error
   * we will play it safe and require an entire texel.
   */
  slack_requirement = lod_factor;

  /* store the image coordinate relative to the root fastuidraw::Image */
  image_coordinate =
    fastuidraw_compute_root_image_coordinate(master_tile_texel_coord, image_info);

  /* compute the tile range so that we can decide whether or not
   * to use the sampler for linear filtering.
   */
  fastuidraw_image_atlas_compute_tile_range(image_coordinate, min_tile_dist, max_tile_dist);

  if (max_tile_dist.x >= slack_requirement
      && max_tile_dist.y >= slack_requirement
      && min_tile_dist.x <= -slack_requirement
      && min_tile_dist.y <= -slack_requirement)
    {
      fastuidraw_compute_image_atlas_coord_type atlas_location;

      fastuidraw_compute_image_atlas_coord(master_tile_texel_coord,
                                           index_layer, image_info.num_levels,
                                           atlas_location);

      image_color = textureLod(fastuidraw_imageAtlasLinear,
                               vec3(atlas_location.unnormalized_texcoord_xy * fastuidraw_imageAtlasLinear_size_reciprocal,
                                    atlas_location.layer),
                               float(lod_i));
    }
  else
    {
      fastuidraw_image_texture_gather_output_type gather;
      float inverse_lod_factor = 1.0f / lod_factor;

      /* Sighs, we need to do the bilinear filter ourselves because
       * atleas one of the neighboring texels is in a different tile.
       */
      fastuidraw_atlas_image_gather(lod_i, lod_factor, inverse_lod_factor,
                                    master_tile_texel_coord,
                                    index_layer, image_info,
                                    gather);

      vec4 c0, c1;

      c0 = mix(gather.c00, gather.c01, fract(inverse_lod_factor * gather.atlas_location_t00.unnormalized_texcoord_xy.y));
      c1 = mix(gather.c10, gather.c11, fract(inverse_lod_factor * gather.atlas_location_t00.unnormalized_texcoord_xy.y));

      image_color = mix(c0, c1, fract(inverse_lod_factor * gather.atlas_location_t00.unnormalized_texcoord_xy.x));
    }
  return image_color;
}

/*!
 * Perform linear filtering sampling on a sub-image. Only available if
 * \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is not defined.
 * \param image_coordinate texel coordinate relative to the sub-image specified
 *                         by image_info
 * \param image_info describes the fastuidraw::Image and the sub-image within it
 *                   to sample
 * \param lod_i which mipmap level to take (level = 0 is the base image)
 */
vec4
fastuidraw_linear_filter_atlas_image(in vec2 image_coordinate,
                                     in fastuidraw_image_extended_info_type image_info,
                                     in int lod_i)
{
  vec2 master_tile_texel_coord;
  float lod_factor;

  lod_factor = float(1 << lod_i);

  /* clamp the image_coordinate to within the sub-image. */
  image_coordinate =
    fastuidraw_image_coordinate_clamp_for_linear_filtering(image_coordinate,
                                                           image_info, lod_factor);

  /* get the master index tile coordinate */
  master_tile_texel_coord =
    fastuidraw_compute_master_index_tile_coordinate(image_coordinate, image_info);

  return fastuidraw_linear_filter_atlas_image(master_tile_texel_coord,
                                              image_info.master_index_tile_layer,
                                              image_info.base,
                                              lod_i, lod_factor);
}

/*!
 * Perform cubic filtering sampling on a sub-image. Only available if
 * \ref FASTUIDRAW_IMAGE_ATLAS_DISABLED is not defined.
 * \param image_coordinate texel coordinate relative to the sub-image specified
 *                         by image_info
 * \param image_info describes the fastuidraw::Image and the sub-image within it
 *                   to sample
 */
vec4
fastuidraw_cubic_filter_atlas_image(in vec2 image_coordinate,
                                    in fastuidraw_image_extended_info_type image_info)
{
  vec4 image_color;
  vec2 master_tile_texel_coord;
  vec2 fract_image_coordinate;
  vec2 min_tile_dist, max_tile_dist, linear_weight;
  vec4 x_weights, y_weights, weight_sums, recip_weight_sums;
  vec4 t00, t10, t01, t11;
  uint index_layer;

  index_layer = image_info.master_index_tile_layer;

  image_coordinate =
    fastuidraw_image_coordinate_clamp_for_cubic_filtering(image_coordinate, image_info);

  master_tile_texel_coord =
    fastuidraw_compute_master_index_tile_coordinate(image_coordinate, image_info);

  /* slide the input coordinate by 0.5 image texels to the left/bottom */
  master_tile_texel_coord -= vec2(0.5 * image_info.base.image_texel_size_on_master_index_tile);

  /* now store the image coordinate relative to the root fastuidraw::Image */
  image_coordinate = fastuidraw_compute_image_coordinate(master_tile_texel_coord, image_info);

  /* compute the tile range so that we can decide whether or not
   * to use the sampler directly for linear filtering.
   */
  fastuidraw_image_atlas_compute_tile_range(image_coordinate, min_tile_dist, max_tile_dist);

  fract_image_coordinate = fract(image_coordinate);
  image_coordinate -= fract_image_coordinate;

  x_weights = fastuidraw_cubic_weights(fract_image_coordinate.x);
  y_weights = fastuidraw_cubic_weights(fract_image_coordinate.y);
  weight_sums = vec4(x_weights.x + x_weights.y, x_weights.z + x_weights.w,
                     y_weights.x + y_weights.y, y_weights.z + y_weights.w);
  recip_weight_sums = vec4(1.0) / weight_sums;

  linear_weight.x = weight_sums.y / (weight_sums.x + weight_sums.y);
  linear_weight.y = weight_sums.w / (weight_sums.z + weight_sums.w);

  if (min_tile_dist.x <= -1.5
      && min_tile_dist.y <= -1.5
      && max_tile_dist.x >= 2.5
      && max_tile_dist.y >= 2.5)
    {
      fastuidraw_compute_image_atlas_coord_type atlas_location;
      fastuidraw_compute_image_atlas_coord(master_tile_texel_coord, index_layer,
                                           image_info.base.num_levels, atlas_location);

      /* Cubic filtering by realizing cubic-filtering as repeated
       * bilinear filtering, see GPU Gems 2, Chapter 20.
       * Code inspired by StackOverflow (http://stackoverflow.com/questions/13501081/efficient-bicubic-filtering-code-in-glsl)
       * and from Shiny Pixels (http://vec3.ca/bicubic-filtering-in-fewer-taps/)
       */
      vec2 texel_coord;
      vec4 corner_coords, texture_coords;

      texel_coord = atlas_location.unnormalized_texcoord_xy;
      texel_coord -= fract_image_coordinate;

      corner_coords = texel_coord.xxyy;
      corner_coords.xz -= vec2(0.5);
      corner_coords.yw += vec2(1.5);

      texture_coords = corner_coords + vec4(x_weights.y, x_weights.w, y_weights.y, y_weights.w) * recip_weight_sums;
      texture_coords *= fastuidraw_imageAtlasLinear_size_reciprocal.xyxy;

      t00 = textureLod(fastuidraw_imageAtlasLinear, vec3(texture_coords.xz, atlas_location.layer), 0.0);
      t10 = textureLod(fastuidraw_imageAtlasLinear, vec3(texture_coords.yz, atlas_location.layer), 0.0);
      t01 = textureLod(fastuidraw_imageAtlasLinear, vec3(texture_coords.xw, atlas_location.layer), 0.0);
      t11 = textureLod(fastuidraw_imageAtlasLinear, vec3(texture_coords.yw, atlas_location.layer), 0.0);
    }
  else
    {
      vec2 master_texel_coord;
      vec4 corner_coords, offset_coords, master_coords;

      master_texel_coord = master_tile_texel_coord;
      master_texel_coord -= fract_image_coordinate * vec2(image_info.base.image_texel_size_on_master_index_tile);

      corner_coords = master_texel_coord.xxyy;
      corner_coords.xz -= vec2(0.5 * image_info.base.image_texel_size_on_master_index_tile);
      corner_coords.yw += vec2(1.5 * image_info.base.image_texel_size_on_master_index_tile);

      offset_coords = vec4(x_weights.y, x_weights.w, y_weights.y, y_weights.w) * recip_weight_sums;
      offset_coords *= image_info.base.image_texel_size_on_master_index_tile;

      master_coords = corner_coords + offset_coords;
      t00 = fastuidraw_linear_filter_atlas_image(master_coords.xz, index_layer, image_info.base, 0, 1.0);
      t10 = fastuidraw_linear_filter_atlas_image(master_coords.yz, index_layer, image_info.base, 0, 1.0);
      t01 = fastuidraw_linear_filter_atlas_image(master_coords.xw, index_layer, image_info.base, 0, 1.0);
      t11 = fastuidraw_linear_filter_atlas_image(master_coords.yw, index_layer, image_info.base, 0, 1.0);
    }

  image_color = mix(mix(t00, t10, linear_weight.x),
                    mix(t01, t11, linear_weight.x),
                    linear_weight.y);

  return image_color;
}

#endif
/*! @} */