mutter/cogl/cogl/cogl-rectangle-map.c

/*
 * Cogl
 *
 * A Low Level GPU Graphics and Utilities API
 *
 * Copyright (C) 2009 Intel Corporation.
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use, copy,
 * modify, merge, publish, distribute, sublicense, and/or sell copies
 * of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 *
 *
 * Authors:
 *  Neil Roberts   <neil@linux.intel.com>
 */

#include "cogl-config.h"

#include <glib.h>

#include "cogl-util.h"
#include "cogl-rectangle-map.h"
#include "cogl-debug.h"

/* Implements a data structure which keeps track of unused
   sub-rectangles within a larger rectangle using a binary tree
   structure. The algorithm for this is based on the description here:

   http://www.blackpawn.com/texts/lightmaps/default.html
*/

typedef struct _CoglRectangleMapNode       CoglRectangleMapNode;
typedef struct _CoglRectangleMapStackEntry CoglRectangleMapStackEntry;

typedef void (* CoglRectangleMapInternalForeachCb) (CoglRectangleMapNode *node,
                                                    void *data);

typedef enum
{
  COGL_RECTANGLE_MAP_BRANCH,
  COGL_RECTANGLE_MAP_FILLED_LEAF,
  COGL_RECTANGLE_MAP_EMPTY_LEAF
} CoglRectangleMapNodeType;

struct _CoglRectangleMap
{
  CoglRectangleMapNode *root;

  unsigned int n_rectangles;

  unsigned int space_remaining;

  GDestroyNotify value_destroy_func;

  /* Stack used for walking the structure. This is only used during
     the lifetime of a single function call but it is kept here as an
     optimisation to avoid reallocating it every time it is needed */
  GArray *stack;
};

struct _CoglRectangleMapNode
{
  CoglRectangleMapNodeType type;

  CoglRectangleMapEntry rectangle;

  unsigned int largest_gap;

  CoglRectangleMapNode *parent;

  union
  {
    /* Fields used when this is a branch */
    struct
    {
      CoglRectangleMapNode *left;
      CoglRectangleMapNode *right;
    } branch;

    /* Field used when this is a filled leaf */
    void *data;
  } d;
};

struct _CoglRectangleMapStackEntry
{
  /* The node to search */
  CoglRectangleMapNode *node;
  /* Index of next branch of this node to explore. Basically either 0
     to go left or 1 to go right */
  gboolean next_index;
};

static CoglRectangleMapNode *
_cogl_rectangle_map_node_new (void)
{
  return g_new0 (CoglRectangleMapNode, 1);
}

static void
_cogl_rectangle_map_node_free (CoglRectangleMapNode *node)
{
  g_free (node);
}

CoglRectangleMap *
_cogl_rectangle_map_new (unsigned int width,
                         unsigned int height,
                         GDestroyNotify value_destroy_func)
{
  CoglRectangleMap *map = g_new (CoglRectangleMap, 1);
  CoglRectangleMapNode *root = _cogl_rectangle_map_node_new ();

  root->type = COGL_RECTANGLE_MAP_EMPTY_LEAF;
  root->parent = NULL;
  root->rectangle.x = 0;
  root->rectangle.y = 0;
  root->rectangle.width = width;
  root->rectangle.height = height;
  root->largest_gap = width * height;

  map->root = root;
  map->n_rectangles = 0;
  map->value_destroy_func = value_destroy_func;
  map->space_remaining = width * height;

  map->stack = g_array_new (FALSE, FALSE, sizeof (CoglRectangleMapStackEntry));

  return map;
}

static void
_cogl_rectangle_map_stack_push (GArray *stack,
                                CoglRectangleMapNode *node,
                                gboolean next_index)
{
  CoglRectangleMapStackEntry *new_entry;

  g_array_set_size (stack, stack->len + 1);

  new_entry = &g_array_index (stack, CoglRectangleMapStackEntry,
                              stack->len - 1);

  new_entry->node = node;
  new_entry->next_index = next_index;
}

static void
_cogl_rectangle_map_stack_pop (GArray *stack)
{
  g_array_set_size (stack, stack->len - 1);
}

static CoglRectangleMapStackEntry *
_cogl_rectangle_map_stack_get_top (GArray *stack)
{
  return &g_array_index (stack, CoglRectangleMapStackEntry,
                         stack->len - 1);
}

static CoglRectangleMapNode *
_cogl_rectangle_map_node_split_horizontally (CoglRectangleMapNode *node,
                                             unsigned int left_width)
{
  /* Splits the node horizontally (according to emacs' definition, not
     vim) by converting it to a branch and adding two new leaf
     nodes. The leftmost branch will have the width left_width and
     will be returned. If the node is already just the right size it
     won't do anything */

  CoglRectangleMapNode *left_node, *right_node;

  if (node->rectangle.width == left_width)
    return node;

  left_node = _cogl_rectangle_map_node_new ();
  left_node->type = COGL_RECTANGLE_MAP_EMPTY_LEAF;
  left_node->parent = node;
  left_node->rectangle.x = node->rectangle.x;
  left_node->rectangle.y = node->rectangle.y;
  left_node->rectangle.width = left_width;
  left_node->rectangle.height = node->rectangle.height;
  left_node->largest_gap = (left_node->rectangle.width *
                            left_node->rectangle.height);
  node->d.branch.left = left_node;

  right_node = _cogl_rectangle_map_node_new ();
  right_node->type = COGL_RECTANGLE_MAP_EMPTY_LEAF;
  right_node->parent = node;
  right_node->rectangle.x = node->rectangle.x + left_width;
  right_node->rectangle.y = node->rectangle.y;
  right_node->rectangle.width = node->rectangle.width - left_width;
  right_node->rectangle.height = node->rectangle.height;
  right_node->largest_gap = (right_node->rectangle.width *
                             right_node->rectangle.height);
  node->d.branch.right = right_node;

  node->type = COGL_RECTANGLE_MAP_BRANCH;

  return left_node;
}

static CoglRectangleMapNode *
_cogl_rectangle_map_node_split_vertically (CoglRectangleMapNode *node,
                                           unsigned int top_height)
{
  /* Splits the node vertically (according to emacs' definition, not
     vim) by converting it to a branch and adding two new leaf
     nodes. The topmost branch will have the height top_height and
     will be returned. If the node is already just the right size it
     won't do anything */

  CoglRectangleMapNode *top_node, *bottom_node;

  if (node->rectangle.height == top_height)
    return node;

  top_node = _cogl_rectangle_map_node_new ();
  top_node->type = COGL_RECTANGLE_MAP_EMPTY_LEAF;
  top_node->parent = node;
  top_node->rectangle.x = node->rectangle.x;
  top_node->rectangle.y = node->rectangle.y;
  top_node->rectangle.width = node->rectangle.width;
  top_node->rectangle.height = top_height;
  top_node->largest_gap = (top_node->rectangle.width *
                           top_node->rectangle.height);
  node->d.branch.left = top_node;

  bottom_node = _cogl_rectangle_map_node_new ();
  bottom_node->type = COGL_RECTANGLE_MAP_EMPTY_LEAF;
  bottom_node->parent = node;
  bottom_node->rectangle.x = node->rectangle.x;
  bottom_node->rectangle.y = node->rectangle.y + top_height;
  bottom_node->rectangle.width = node->rectangle.width;
  bottom_node->rectangle.height = node->rectangle.height - top_height;
  bottom_node->largest_gap = (bottom_node->rectangle.width *
                              bottom_node->rectangle.height);
  node->d.branch.right = bottom_node;

  node->type = COGL_RECTANGLE_MAP_BRANCH;

  return top_node;
}

gboolean
_cogl_rectangle_map_add (CoglRectangleMap *map,
                         unsigned int width,
                         unsigned int height,
                         void *data,
                         CoglRectangleMapEntry *rectangle)
{
  unsigned int rectangle_size = width * height;
  /* Stack of nodes to search in */
  GArray *stack = map->stack;
  CoglRectangleMapNode *found_node = NULL;

  /* Zero-sized rectangles break the algorithm for removing rectangles
     so we'll disallow them */
  g_return_val_if_fail (width > 0 && height > 0, FALSE);

  /* Start with the root node */
  g_array_set_size (stack, 0);
  _cogl_rectangle_map_stack_push (stack, map->root, FALSE);

  /* Depth-first search for an empty node that is big enough */
  while (stack->len > 0)
    {
      CoglRectangleMapStackEntry *stack_top;
      CoglRectangleMapNode *node;
      int next_index;

      /* Pop an entry off the stack */
      stack_top = _cogl_rectangle_map_stack_get_top (stack);
      node = stack_top->node;
      next_index = stack_top->next_index;
      _cogl_rectangle_map_stack_pop (stack);

      /* Regardless of the type of the node, there's no point
         descending any further if the new rectangle won't fit within
         it */
      if (node->rectangle.width >= width &&
          node->rectangle.height >= height &&
          node->largest_gap >= rectangle_size)
        {
          if (node->type == COGL_RECTANGLE_MAP_EMPTY_LEAF)
            {
              /* We've found a node we can use */
              found_node = node;
              break;
            }
          else if (node->type == COGL_RECTANGLE_MAP_BRANCH)
            {
              if (next_index)
                /* Try the right branch */
                _cogl_rectangle_map_stack_push (stack,
                                                node->d.branch.right,
                                                0);
              else
                {
                  /* Make sure we remember to try the right branch once
                     we've finished descending the left branch */
                  _cogl_rectangle_map_stack_push (stack,
                                                  node,
                                                  1);
                  /* Try the left branch */
                  _cogl_rectangle_map_stack_push (stack,
                                                  node->d.branch.left,
                                                  0);
                }
            }
        }
    }

  if (found_node)
    {
      CoglRectangleMapNode *node;

      /* Split according to whichever axis will leave us with the
         largest space */
      if (found_node->rectangle.width - width >
          found_node->rectangle.height - height)
        {
          found_node =
            _cogl_rectangle_map_node_split_horizontally (found_node, width);
          found_node =
            _cogl_rectangle_map_node_split_vertically (found_node, height);
        }
      else
        {
          found_node =
            _cogl_rectangle_map_node_split_vertically (found_node, height);
          found_node =
            _cogl_rectangle_map_node_split_horizontally (found_node, width);
        }

      found_node->type = COGL_RECTANGLE_MAP_FILLED_LEAF;
      found_node->d.data = data;
      found_node->largest_gap = 0;
      if (rectangle)
        *rectangle = found_node->rectangle;

      /* Walk back up the tree and update the stored largest gap for
         the node's sub tree */
      for (node = found_node->parent; node; node = node->parent)
        {
          /* This node is a parent so it should always be a branch */
          g_assert (node->type == COGL_RECTANGLE_MAP_BRANCH);

          node->largest_gap = MAX (node->d.branch.left->largest_gap,
                                   node->d.branch.right->largest_gap);
        }

      /* There is now an extra rectangle in the map */
      map->n_rectangles++;
      /* and less space */
      map->space_remaining -= rectangle_size;

      return TRUE;
    }
  else
    return FALSE;
}

void
_cogl_rectangle_map_remove (CoglRectangleMap *map,
                            const CoglRectangleMapEntry *rectangle)
{
  CoglRectangleMapNode *node = map->root;
  unsigned int rectangle_size = rectangle->width * rectangle->height;

  /* We can do a binary-chop down the search tree to find the rectangle */
  while (node->type == COGL_RECTANGLE_MAP_BRANCH)
    {
      CoglRectangleMapNode *left_node = node->d.branch.left;

      /* If and only if the rectangle is in the left node then the x,y
         position of the rectangle will be within the node's
         rectangle */
      if (rectangle->x < left_node->rectangle.x + left_node->rectangle.width &&
          rectangle->y < left_node->rectangle.y + left_node->rectangle.height)
        /* Go left */
        node = left_node;
      else
        /* Go right */
        node = node->d.branch.right;
    }

  /* Make sure we found the right node */
  if (node->type != COGL_RECTANGLE_MAP_FILLED_LEAF ||
      node->rectangle.x != rectangle->x ||
      node->rectangle.y != rectangle->y ||
      node->rectangle.width != rectangle->width ||
      node->rectangle.height != rectangle->height)
    /* This should only happen if someone tried to remove a rectangle
       that was not in the map so something has gone wrong */
    g_return_if_reached ();
  else
    {
      /* Convert the node back to an empty node */
      if (map->value_destroy_func)
        map->value_destroy_func (node->d.data);
      node->type = COGL_RECTANGLE_MAP_EMPTY_LEAF;
      node->largest_gap = rectangle_size;

      /* Walk back up the tree combining branch nodes that have two
         empty leaves back into a single empty leaf */
      for (node = node->parent; node; node = node->parent)
        {
          /* This node is a parent so it should always be a branch */
          g_assert (node->type == COGL_RECTANGLE_MAP_BRANCH);

          if (node->d.branch.left->type == COGL_RECTANGLE_MAP_EMPTY_LEAF &&
              node->d.branch.right->type == COGL_RECTANGLE_MAP_EMPTY_LEAF)
            {
              _cogl_rectangle_map_node_free (node->d.branch.left);
              _cogl_rectangle_map_node_free (node->d.branch.right);
              node->type = COGL_RECTANGLE_MAP_EMPTY_LEAF;

              node->largest_gap = (node->rectangle.width *
                                   node->rectangle.height);
            }
          else
            break;
        }

      /* Reduce the amount of space remaining in all of the parents
         further up the chain */
      for (; node; node = node->parent)
        node->largest_gap = MAX (node->d.branch.left->largest_gap,
                                 node->d.branch.right->largest_gap);

      /* There is now one less rectangle */
      g_assert (map->n_rectangles > 0);
      map->n_rectangles--;
      /* and more space */
      map->space_remaining += rectangle_size;
    }
}

unsigned int
_cogl_rectangle_map_get_width (CoglRectangleMap *map)
{
  return map->root->rectangle.width;
}

unsigned int
_cogl_rectangle_map_get_height (CoglRectangleMap *map)
{
  return map->root->rectangle.height;
}

unsigned int
_cogl_rectangle_map_get_remaining_space (CoglRectangleMap *map)
{
  return map->space_remaining;
}

unsigned int
_cogl_rectangle_map_get_n_rectangles (CoglRectangleMap *map)
{
  return map->n_rectangles;
}

static void
_cogl_rectangle_map_internal_foreach (CoglRectangleMap *map,
                                      CoglRectangleMapInternalForeachCb func,
                                      void *data)
{
  /* Stack of nodes to search in */
  GArray *stack = map->stack;

  /* Start with the root node */
  g_array_set_size (stack, 0);
  _cogl_rectangle_map_stack_push (stack, map->root, 0);

  /* Iterate all nodes depth-first */
  while (stack->len > 0)
    {
      CoglRectangleMapStackEntry *stack_top =
        _cogl_rectangle_map_stack_get_top (stack);
      CoglRectangleMapNode *node = stack_top->node;

      switch (node->type)
        {
        case COGL_RECTANGLE_MAP_BRANCH:
          if (stack_top->next_index == 0)
            {
              /* Next time we come back to this node, go to the right */
              stack_top->next_index = 1;

              /* Explore the left branch next */
              _cogl_rectangle_map_stack_push (stack,
                                              node->d.branch.left,
                                              0);
            }
          else if (stack_top->next_index == 1)
            {
              /* Next time we come back to this node, stop processing it */
              stack_top->next_index = 2;

              /* Explore the right branch next */
              _cogl_rectangle_map_stack_push (stack,
                                              node->d.branch.right,
                                              0);
            }
          else
            {
              /* We're finished with this node so we can call the callback */
              func (node, data);
              _cogl_rectangle_map_stack_pop (stack);
            }
          break;

        default:
          /* Some sort of leaf node, just call the callback */
          func (node, data);
          _cogl_rectangle_map_stack_pop (stack);
          break;
        }
    }

  /* The stack should now be empty */
  g_assert (stack->len == 0);
}

typedef struct _CoglRectangleMapForeachClosure
{
  CoglRectangleMapCallback callback;
  void *data;
} CoglRectangleMapForeachClosure;

static void
_cogl_rectangle_map_foreach_cb (CoglRectangleMapNode *node, void *data)
{
  CoglRectangleMapForeachClosure *closure = data;

  if (node->type == COGL_RECTANGLE_MAP_FILLED_LEAF)
    closure->callback (&node->rectangle, node->d.data, closure->data);
}

void
_cogl_rectangle_map_foreach (CoglRectangleMap *map,
                             CoglRectangleMapCallback callback,
                             void *data)
{
  CoglRectangleMapForeachClosure closure;

  closure.callback = callback;
  closure.data = data;

  _cogl_rectangle_map_internal_foreach (map,
                                        _cogl_rectangle_map_foreach_cb,
                                        &closure);
}

static void
_cogl_rectangle_map_free_cb (CoglRectangleMapNode *node, void *data)
{
  CoglRectangleMap *map = data;

  if (node->type == COGL_RECTANGLE_MAP_FILLED_LEAF && map->value_destroy_func)
    map->value_destroy_func (node->d.data);

  _cogl_rectangle_map_node_free (node);
}

void
_cogl_rectangle_map_free (CoglRectangleMap *map)
{
  _cogl_rectangle_map_internal_foreach (map,
                                        _cogl_rectangle_map_free_cb,
                                        map);

  g_array_free (map->stack, TRUE);

  g_free (map);
}