Class STBRectPack
Useful for e.g. packing rectangular textures into an atlas. Does not do rotation.
This library currently uses the Skyline Bottom-Left algorithm. Not necessarily the awesomest packing method, but better than the totally naive one in stb_truetype (which is primarily what this is meant to replace).
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
Mostly for internal use, but this is the maximum supported coordinate value.static final int
Packing heuristicsstatic final int
Packing heuristicsstatic final int
Packing heuristics -
Method Summary
Modifier and TypeMethodDescriptionstatic void
nstbrp_init_target
(long context, int width, int height, long nodes, int num_nodes) Unsafe version of:init_target
static int
nstbrp_pack_rects
(long context, long rects, int num_rects) Unsafe version of:pack_rects
static void
nstbrp_setup_allow_out_of_mem
(long context, int allow_out_of_mem) Unsafe version of:setup_allow_out_of_mem
static void
nstbrp_setup_heuristic
(long context, int heuristic) Unsafe version of:setup_heuristic
static void
stbrp_init_target
(STBRPContext context, int width, int height, STBRPNode.Buffer nodes) Initialize a rectangle packer to: pack a rectangle that iswidth
byheight
in dimensions using temporary storage provided by the arraynodes
, which isnum_nodes
long.static int
stbrp_pack_rects
(STBRPContext context, STBRPRect.Buffer rects) Assigns packed locations to rectangles.static void
stbrp_setup_allow_out_of_mem
(STBRPContext context, boolean allow_out_of_mem) Optionally call this function after init but before doing any packing to change the handling of the out-of-temp-memory scenario, described ininit_target
.static void
stbrp_setup_heuristic
(STBRPContext context, int heuristic) Optionally select which packing heuristic the library should use.
-
Field Details
-
STBRP__MAXVAL
public static final int STBRP__MAXVALMostly for internal use, but this is the maximum supported coordinate value.- See Also:
-
STBRP_HEURISTIC_Skyline_default
public static final int STBRP_HEURISTIC_Skyline_defaultPacking heuristicsEnum values:
- See Also:
-
STBRP_HEURISTIC_Skyline_BL_sortHeight
public static final int STBRP_HEURISTIC_Skyline_BL_sortHeightPacking heuristicsEnum values:
- See Also:
-
STBRP_HEURISTIC_Skyline_BF_sortHeight
public static final int STBRP_HEURISTIC_Skyline_BF_sortHeightPacking heuristicsEnum values:
- See Also:
-
-
Method Details
-
nstbrp_pack_rects
public static int nstbrp_pack_rects(long context, long rects, int num_rects) Unsafe version of:pack_rects
- Parameters:
num_rects
- the number of structs inrects
-
stbrp_pack_rects
Assigns packed locations to rectangles. The rectangles are of typeSTBRPRect
, stored in the arrayrects
, and there arenum_rects
many of them.Rectangles which are successfully packed have the
was_packed
flag set to a non-zero value andx
andy
store the minimum location on each axis (i.e. bottom-left in cartesian coordinates, top-left if you imagine y increasing downwards). Rectangles which do not fit have thewas_packed
flag set to 0.You should not try to access the
rects
array from another thread while this function is running, as the function temporarily reorders the array while it executes.To pack into another rectangle, you need to call
init_target
again. To continue packing into the same rectangle, you can call this function again. Calling this multiple times with multiple rect arrays will probably produce worse packing results than calling it a single time with the full rectangle array, but the option is available.- Parameters:
context
- anSTBRPContext
structrects
- an array ofSTBRPRect
structs- Returns:
- 1 if all of the rectangles were successfully packed and 0 otherwise
-
nstbrp_init_target
public static void nstbrp_init_target(long context, int width, int height, long nodes, int num_nodes) Unsafe version of:init_target
- Parameters:
num_nodes
- the number of structs innodes
-
stbrp_init_target
public static void stbrp_init_target(STBRPContext context, int width, int height, STBRPNode.Buffer nodes) Initialize a rectangle packer to: pack a rectangle that iswidth
byheight
in dimensions using temporary storage provided by the arraynodes
, which isnum_nodes
long.You must call this function every time you start packing into a new target.
There is no "shutdown" function. The
nodes
memory must stay valid for the followingpack_rects
call (or calls), but can be freed after the call (or calls) finish.Note: to guarantee best results, either:
- make sure
num_nodes ≥ width
- or, call
setup_allow_out_of_mem
withallow_out_of_mem = 1
If you don't do either of the above things, widths will be quantized to multiples of small integers to guarantee the algorithm doesn't run out of temporary storage.
If you do #2, then the non-quantized algorithm will be used, but the algorithm may run out of temporary storage and be unable to pack some rectangles.
- Parameters:
context
- anSTBRPContext
structwidth
- the rectangle widthheight
- the rectangle heightnodes
- an array ofSTBRPNode
structs
- make sure
-
nstbrp_setup_allow_out_of_mem
public static void nstbrp_setup_allow_out_of_mem(long context, int allow_out_of_mem) Unsafe version of:setup_allow_out_of_mem
-
stbrp_setup_allow_out_of_mem
Optionally call this function after init but before doing any packing to change the handling of the out-of-temp-memory scenario, described ininit_target
. If you call init again, this will be reset to the default (false).- Parameters:
context
- anSTBRPContext
structallow_out_of_mem
- 1 to allow running out of temporary storage
-
nstbrp_setup_heuristic
public static void nstbrp_setup_heuristic(long context, int heuristic) Unsafe version of:setup_heuristic
-
stbrp_setup_heuristic
Optionally select which packing heuristic the library should use. Different heuristics will produce better/worse results for different data sets. If you call init again, this will be reset to the default.- Parameters:
context
- anSTBRPContext
structheuristic
- the packing heuristic
-