Top Description Fields Constructors Methods
org.lwjgl.stb

public Class STBRectPack

extends Object
Class Inheritance
Imports
org.lwjgl.system.*
Native bindings to stb_rect_pack.h from the stb library.

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 TypeField and Description
public static final int
STBRP__MAXVAL

Mostly for internal use, but this is the maximum supported coordinate value.

public static final int
STBRP_HEURISTIC_Skyline_BF_sortHeight

Packing heuristics Enum values:

public static final int
STBRP_HEURISTIC_Skyline_BL_sortHeight

Packing heuristics Enum values:

public static final int
STBRP_HEURISTIC_Skyline_default

Packing heuristics Enum values:

Constructor Summary

AccessConstructor and Description
protected
STBRectPack()

Method Summary

Modifier and TypeMethod and Description
public static native void
nstbrp_init_target(long context, int width, int height, long nodes, int
the number of structs in nodes
num_nodes)

Unsafe version of: init_target

public static native int
nstbrp_pack_rects(long context, long rects, int
the number of structs in rects
num_rects)

Unsafe version of: pack_rects

public static native void
nstbrp_setup_allow_out_of_mem(long context, int allow_out_of_mem)

Unsafe version of: setup_allow_out_of_mem

public static native void
nstbrp_setup_heuristic(long context, int heuristic)

Unsafe version of: setup_heuristic

public static void
stbrp_init_target(STBRPContext
an STBRPContext struct
context, int
the rectangle width
width, int
the rectangle height
height, STBRPNode.Buffer
an array of STBRPNode structs
nodes)

Initialize a rectangle packer to: pack a rectangle that is width by height in dimensions using temporary storage provided by the array nodes, which is num_nodes long.

public static int

Returns:

1 if all of the rectangles were successfully packed and 0 otherwise
stbrp_pack_rects(STBRPContext
an STBRPContext struct
context, STBRPRect.Buffer
an array of STBRPRect structs
rects)

Assigns packed locations to rectangles.

public static void
stbrp_setup_allow_out_of_mem(STBRPContext
an STBRPContext struct
context, boolean
1 to allow running out of temporary storage
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 in init_target.

public static void
stbrp_setup_heuristic(STBRPContext
an STBRPContext struct
context, int
the packing heuristic
heuristic)

Optionally select which packing heuristic the library should use.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

STBRP__MAXVALback to summary
public static final int STBRP__MAXVAL

Mostly for internal use, but this is the maximum supported coordinate value.

STBRP_HEURISTIC_Skyline_BF_sortHeightback to summary
public static final int STBRP_HEURISTIC_Skyline_BF_sortHeight

Packing heuristics

Enum values:
STBRP_HEURISTIC_Skyline_BL_sortHeightback to summary
public static final int STBRP_HEURISTIC_Skyline_BL_sortHeight

Packing heuristics

Enum values:
STBRP_HEURISTIC_Skyline_defaultback to summary
public static final int STBRP_HEURISTIC_Skyline_default

Packing heuristics

Enum values:

Constructor Detail

STBRectPackback to summary
protected STBRectPack()

Method Detail

nstbrp_init_targetback to summary
public static native void nstbrp_init_target(long context, int width, int height, long nodes, int num_nodes)

Unsafe version of: init_target

Parameters
num_nodes:int

the number of structs in nodes

nstbrp_pack_rectsback to summary
public static native int nstbrp_pack_rects(long context, long rects, int num_rects)

Unsafe version of: pack_rects

Parameters
num_rects:int

the number of structs in rects

nstbrp_setup_allow_out_of_memback to summary
public static native void nstbrp_setup_allow_out_of_mem(long context, int allow_out_of_mem)

Unsafe version of: setup_allow_out_of_mem

nstbrp_setup_heuristicback to summary
public static native void nstbrp_setup_heuristic(long context, int heuristic)

Unsafe version of: setup_heuristic

stbrp_init_targetback to summary
public static void stbrp_init_target(STBRPContext context, int width, int height, STBRPNode.Buffer nodes)

Initialize a rectangle packer to: pack a rectangle that is width by height in dimensions using temporary storage provided by the array nodes, which is num_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 following pack_rects call (or calls), but can be freed after the call (or calls) finish.

Note

to guarantee best results, either:

  1. make sure num_nodes ≥ width
  2. or, call setup_allow_out_of_mem with allow_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:STBRPContext

an STBRPContext struct

width:int

the rectangle width

height:int

the rectangle height

nodes:STBRPNode.Buffer

an array of STBRPNode structs

stbrp_pack_rectsback to summary
public static int stbrp_pack_rects(STBRPContext context, STBRPRect.Buffer rects)

Assigns packed locations to rectangles. The rectangles are of type STBRPRect, stored in the array rects, and there are num_rects many of them.

Rectangles which are successfully packed have the was_packed flag set to a non-zero value and x and y 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 the was_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:STBRPContext

an STBRPContext struct

rects:STBRPRect.Buffer

an array of STBRPRect structs

Returns:int

1 if all of the rectangles were successfully packed and 0 otherwise

stbrp_setup_allow_out_of_memback to summary
public 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 in init_target. If you call init again, this will be reset to the default (false).

Parameters
context:STBRPContext

an STBRPContext struct

allow_out_of_mem:boolean

1 to allow running out of temporary storage

stbrp_setup_heuristicback to summary
public static void stbrp_setup_heuristic(STBRPContext context, int 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:STBRPContext

an STBRPContext struct

heuristic:int

the packing heuristic