src/include/eina_rectangle.h

   1 /* EINA - EFL data type library
   2  * Copyright (C) 2007-2008 Jorge Luis Zapata Muga
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library;
  16  * if not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef EINA_RECTANGLE_H_
  20 #define EINA_RECTANGLE_H_
  21
  22 #include "eina_types.h"
  23
  24 /**
  25  * @addtogroup Eina_Rectangle_Group Rectangle
  26  *
  27  * @brief These functions provide rectangle management.
  28  */
  29
  30 /**
  31  * @addtogroup Eina_Tools_Group Tools
  32  *
  33  * @{
  34  */
  35
  36 /**
  37  * @defgroup Eina_Rectangle_Group Rectangle
  38  *
  39  * @{
  40  */
  41
  42 /**
  43  * @typedef Eina_Rectangle
  44  * Simple rectangle structure.
  45  */
  46 typedef struct _Eina_Rectangle
  47 {
  48    int x; /**< top-left x co-ordinate of rectangle */
  49    int y; /**< top-left y co-ordinate of rectangle */
  50    int w; /**< width of rectangle */
  51    int h; /**< height of rectangle */
  52 } Eina_Rectangle;
  53
  54 /**
  55  * @typedef Eina_Rectangle_Pool
  56  * Type for an opaque pool of rectangle.
  57  */
  58 typedef struct _Eina_Rectangle_Pool Eina_Rectangle_Pool;
  59
  60 static inline int         eina_spans_intersect(int c1, int l1, int c2, int l2) EINA_WARN_UNUSED_RESULT;
  61 static inline Eina_Bool   eina_rectangle_is_empty(const Eina_Rectangle *r) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
  62 static inline void        eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
  63 static inline Eina_Bool   eina_rectangles_intersect(const Eina_Rectangle *r1, const Eina_Rectangle *r2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
  64 static inline Eina_Bool   eina_rectangle_xcoord_inside(const Eina_Rectangle *r, int x) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
  65 static inline Eina_Bool   eina_rectangle_ycoord_inside(const Eina_Rectangle *r, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
  66 static inline Eina_Bool   eina_rectangle_coords_inside(const Eina_Rectangle *r, int x, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
  67 static inline void        eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2);
  68 static inline Eina_Bool   eina_rectangle_intersection(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
  69 static inline void        eina_rectangle_rescale_in(const Eina_Rectangle *out, const Eina_Rectangle *in, Eina_Rectangle *res) EINA_ARG_NONNULL(1, 2, 3);
  70 static inline void        eina_rectangle_rescale_out(const Eina_Rectangle *out, const Eina_Rectangle *in, Eina_Rectangle *res) EINA_ARG_NONNULL(1, 2, 3);
  71
  72
  73 /**
  74  * @brief Add a rectangle in a new pool.
  75  *
  76  * @param w The width of the rectangle.
  77  * @param h The height of the rectangle.
  78  * @return A newly allocated pool on success, @c NULL otherwise.
  79  *
  80  * This function adds the rectangle of size (@p width, @p height) to a
  81  * new pool. If the pool can not be created, @c NULL is
  82  * returned. Otherwise the newly allocated pool is returned.
  83  */
  84 EAPI Eina_Rectangle_Pool *eina_rectangle_pool_new(int w, int h) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
  85
  86 /**
  87  * @brief Return the pool of the given rectangle.
  88  *
  89  * @param rect The rectangle.
  90  * @return The pool of the given rectangle.
  91  *
  92  * This function returns the pool in which @p rect is. If  @p rect is
  93  * @c NULL, @c NULL is returned.
  94  */
  95 EAPI Eina_Rectangle_Pool *eina_rectangle_pool_get(Eina_Rectangle *rect) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
  96
  97 /**
  98  * @brief Return the width and height of the given pool.
  99  *
 100  * @param pool The pool.
 101  * @param w The returned width.
 102  * @param h The returned height.
 103  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 104  *
 105  * This function returns the width and height of @p pool and store
 106  * them in respectively @p w and @p h if they are not @c NULL. If
 107  * @p pool is @c NULL, #EINA_FALSE is returned. Otherwise #EINA_TRUE is
 108  * returned.
 109  */
 110 EAPI Eina_Bool            eina_rectangle_pool_geometry_get(Eina_Rectangle_Pool *pool, int *w, int *h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 111
 112 /**
 113  * @brief Get the data from the given pool.
 114  *
 115  * @param pool The pool.
 116  * @return The returned data.
 117  *
 118  * This function gets the data from @p pool set by
 119  * eina_rectangle_pool_data_set(). If @p pool is @c NULL, this
 120  * function returns @c NULL.
 121  */
 122 EAPI void                *eina_rectangle_pool_data_get(Eina_Rectangle_Pool *pool) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
 123
 124 /**
 125  * @brief Set the data to the given pool.
 126  *
 127  * @param pool The pool.
 128  * @param data The data to set.
 129  *
 130  * This function sets @p data to @p pool. If @p pool is @c NULL, this
 131  * function does nothing.
 132  */
 133 EAPI void                 eina_rectangle_pool_data_set(Eina_Rectangle_Pool *pool, const void *data) EINA_ARG_NONNULL(1);
 134
 135 /**
 136  * @brief Free the given pool.
 137  *
 138  * @param pool The pool to free.
 139  *
 140  * This function frees the allocated data of @p pool. If @p pool is
 141  * @c NULL, this function returned immediately.
 142  */
 143 EAPI void                 eina_rectangle_pool_free(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1);
 144
 145 /**
 146  * @brief Return the number of rectangles in the given pool.
 147  *
 148  * @param pool The pool.
 149  * @return The number of rectangles in the pool.
 150  *
 151  * This function returns the number of rectangles in @p pool.
 152  */
 153 EAPI int                  eina_rectangle_pool_count(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 154
 155 /**
 156  * @brief Request a rectangle of given size in the given pool.
 157  *
 158  * @param pool The pool.
 159  * @param w The width of the rectangle to request.
 160  * @param h The height of the rectangle to request.
 161  * @return The requested rectangle on success, @c NULL otherwise.
 162  *
 163  * This function retrieve from @p pool the rectangle of width @p w and
 164  * height @p h. If @p pool is @c NULL, or @p w or @p h are non-positive,
 165  * the function returns @c NULL. If @p w or @p h are greater than the
 166  * pool size, the function returns @c NULL. On success, the function
 167  * returns the rectangle which matches the size (@p w, @p h).
 168  * Otherwise it returns @c NULL.
 169  */
 170 EAPI Eina_Rectangle      *eina_rectangle_pool_request(Eina_Rectangle_Pool *pool, int w, int h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
 171
 172 /**
 173  * @brief Remove the given rectangle from the pool.
 174  *
 175  * @param rect The rectangle to remove from the pool.
 176  *
 177  * This function removes @p rect from the pool. If @p rect is
 178  * @c NULL, the function returns immediately. Otherwise it removes @p
 179  * rect from the pool.
 180  */
 181 EAPI void                 eina_rectangle_pool_release(Eina_Rectangle *rect) EINA_ARG_NONNULL(1);
 182
 183 /**
 184  * @def EINA_RECTANGLE_SET
 185  * @brief Macro to set the values of a #Eina_Rectangle.
 186  *
 187  * @param Rectangle The rectangle to set the values.
 188  * @param X The X coordinate of the top left corner of the rectangle.
 189  * @param Y The Y coordinate of the top left corner of the rectangle.
 190  * @param W The width of the rectangle.
 191  * @param H The height of the rectangle.
 192  *
 193  * This macro set the values of @p Rectangle. (@p X, @p Y) is the
 194  * coordinates of the top left corner of @p Rectangle, @p W is its
 195  * width and @p H is its height.
 196  */
 197 #define EINA_RECTANGLE_SET(Rectangle, X, Y, W, H) \
 198   (Rectangle)->x = X;                             \
 199   (Rectangle)->y = Y;                             \
 200   (Rectangle)->w = W;                             \
 201   (Rectangle)->h = H;
 202
 203
 204 /**
 205  * @brief Create a new rectangle.
 206  *
 207  * @param x The X coordinate of the top left corner of the rectangle.
 208  * @param y The Y coordinate of the top left corner of the rectangle.
 209  * @param w The width of the rectangle.
 210  * @param h The height of the rectangle.
 211  * @return The new rectangle on success, @ NULL otherwise.
 212  *
 213  * This function creates a rectangle which top left corner has the
 214  * coordinates (@p x, @p y), with height @p w and height @p h and adds
 215  * it to the rectangles pool. No check is done on @p w and @p h. This
 216  * function returns a new rectangle on success, @c NULL otherwhise.
 217  */
 218 EAPI Eina_Rectangle *eina_rectangle_new(int x, int y, int w, int h) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
 219
 220 /**
 221  * @brief Free the given rectangle.
 222  *
 223  * @param rect The rectangle to free.
 224  *
 225  * This function removes @p rect from the rectangles pool.
 226  */
 227 EAPI void            eina_rectangle_free(Eina_Rectangle *rect) EINA_ARG_NONNULL(1);
 228
 229 #include "eina_inline_rectangle.x"
 230
 231 /**
 232  * @}
 233  */
 234
 235 /**
 236  * @}
 237  */
 238
 239 #endif /*_EINA_RECTANGLE_H_*/