diff options
Diffstat (limited to 'source/blender/blenlib/BLI_boxpack_2d.h')
-rw-r--r-- | source/blender/blenlib/BLI_boxpack_2d.h | 31 |
1 files changed, 30 insertions, 1 deletions
diff --git a/source/blender/blenlib/BLI_boxpack_2d.h b/source/blender/blenlib/BLI_boxpack_2d.h index 7e347d0b0d7..eee1a0d3d41 100644 --- a/source/blender/blenlib/BLI_boxpack_2d.h +++ b/source/blender/blenlib/BLI_boxpack_2d.h @@ -44,7 +44,21 @@ typedef struct BoxPack { int index; } BoxPack; -void BLI_box_pack_2d(BoxPack *boxarray, const unsigned int len, float *r_tot_x, float *r_tot_y); +/** + * Main box-packing function accessed from other functions + * This sets boxes x,y to positive values, sorting from 0,0 outwards. + * There is no limit to the space boxes may take, only that they will be packed + * tightly into the lower left hand corner (0,0) + * + * \param boxarray: a pre-allocated array of boxes. + * only the 'box->x' and 'box->y' are set, 'box->w' and 'box->h' are used, + * 'box->index' is not used at all, the only reason its there + * is that the box array is sorted by area and programs need to be able + * to have some way of writing the boxes back to the original data. + * \param len: the number of boxes in the array. + * \param r_tot_x, r_tot_y: set so you can normalize the data. + */ +void BLI_box_pack_2d(BoxPack *boxarray, unsigned int len, float *r_tot_x, float *r_tot_y); typedef struct FixedSizeBoxPack { struct FixedSizeBoxPack *next, *prev; @@ -52,6 +66,21 @@ typedef struct FixedSizeBoxPack { int w, h; } FixedSizeBoxPack; +/** + * Packs boxes into a fixed area. + * + * Boxes and packed are linked lists containing structs that can be cast to + * #FixedSizeBoxPack (i.e. contains a #FixedSizeBoxPack as its first element). + * Boxes that were packed successfully are placed into *packed and removed from *boxes. + * + * The algorithm is a simplified version of https://github.com/TeamHypersomnia/rectpack2D. + * Better ones could be used, but for the current use case (packing Image tiles into GPU + * textures) this is fine. + * + * Note that packing efficiency depends on the order of the input boxes. Generally speaking, + * larger boxes should come first, though how exactly size is best defined (e.g. area, perimeter) + * depends on the particular application. + */ void BLI_box_pack_2d_fixedarea(struct ListBase *boxes, int width, int height, |