shelf-pack
Version:
A 2D rectangular bin packing data structure that uses the Shelf Best Height Fit heuristic
967 lines (506 loc) • 27.7 kB
HTML
<html>
<head>
<meta charset='utf-8' />
<title> | Documentation</title>
<meta name='viewport' content='width=device-width,initial-scale=1'>
<link href='assets/bass.css' type='text/css' rel='stylesheet' />
<link href='assets/style.css' type='text/css' rel='stylesheet' />
<link href='assets/github.css' type='text/css' rel='stylesheet' />
</head>
<body class='documentation'>
<div class='max-width-4 mx-auto'>
<div class='clearfix md-mxn2'>
<div class='fixed xs-hide fix-3 overflow-auto max-height-100'>
<div class='py1 px2'>
<h3 class='mb0 no-anchor'></h3>
<div class='mb1'><code></code></div>
<input
placeholder='Filter'
id='filter-input'
class='col12 block input'
type='text' />
<div id='toc'>
<ul class='list-reset h5 py1-ul'>
<li><a
href='#ShelfPack'
class=" toggle-sibling">
ShelfPack
<span class='icon'>▸</span>
</a>
<div class='toggle-target display-none'>
<ul class='list-reset py1-ul pl1'>
<li class='h5'>Instance members</li>
<li><a
href='#ShelfPack#pack'
class='regular pre-open'>
#pack
</a></li>
<li><a
href='#ShelfPack#packOne'
class='regular pre-open'>
#packOne
</a></li>
<li><a
href='#ShelfPack#getBin'
class='regular pre-open'>
#getBin
</a></li>
<li><a
href='#ShelfPack#ref'
class='regular pre-open'>
#ref
</a></li>
<li><a
href='#ShelfPack#unref'
class='regular pre-open'>
#unref
</a></li>
<li><a
href='#ShelfPack#clear'
class='regular pre-open'>
#clear
</a></li>
<li><a
href='#ShelfPack#resize'
class='regular pre-open'>
#resize
</a></li>
</ul>
</div>
</li>
<li><a
href='#Bin'
class="">
Bin
</a>
</li>
</ul>
</div>
<div class='mt1 h6 quiet'>
<a href='http://documentation.js.org/reading-documentation.html'>Need help reading this?</a>
</div>
</div>
</div>
<div class='fix-margin-3'>
<div class='px2'>
<section class='py2 clearfix'>
<div class='clearfix'>
<h2 class='fl' id='ShelfPack'>
ShelfPack
</h2>
<a class='fr fill-darken0 round round pad1x quiet h5' href='https://github.com/mapbox/shelf-pack/blob/1da2aaf1600a242fc36c5a3ad2b2b9fda0092182/index.js#L18-L28'>
<span>index.js</span>
</a>
</div>
<p>Create a new ShelfPack bin allocator.</p>
<p>Uses the Shelf Best Height Fit algorithm from
<a href="http://clb.demon.fi/files/RectangleBinPack.pdf">http://clb.demon.fi/files/RectangleBinPack.pdf</a></p>
<div class='pre p1 fill-light'>ShelfPack(w: [<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>], h: [<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>], options: [<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>])</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>w</span> <code class='quiet'>([<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>]
(default <code>64</code>)
)</code> Initial width of the sprite
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>h</span> <code class='quiet'>([<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>]
(default <code>64</code>)
)</code> Initial width of the sprite
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>([<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>])</code>
</div>
<table class='mt1 mb2 fixed-table h5'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<td>Name</td>
<td>Description</td>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.autoResize</span> <code class='quiet'>[<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a>]</code>
(default <code>false</code>)
</td>
<td class='break-word'><span>If
<code>true</code>
, the sprite will automatically grow
</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Example</div>
<pre class='p1 overflow-auto round fill-light'><span class="hljs-keyword">var</span> sprite = <span class="hljs-keyword">new</span> ShelfPack(<span class="hljs-number">64</span>, <span class="hljs-number">64</span>, { autoResize: <span class="hljs-literal">false</span> });</pre>
<div class='py1 quiet mt1 prose-big'>Instance Members</div>
<div class="clearfix">
<div class='keyline-bottom' id='ShelfPack#pack'>
<div class="clearfix small pointer toggle-sibling">
<div class="pad1y contain">
<a class='icon pin-right pad1y dark-link caret-right'></a>
<span class='code strong strong truncate'>pack</span>
<span class='quiet code space-right2'>(bins, [options])</span>
</div>
</div>
<div class="clearfix hidden toggle-target">
<section class='py2 clearfix'>
<p>Batch pack multiple bins into the sprite.</p>
<div class='pre p1 fill-light'>pack(bins: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a><<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>>, options: [<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>]): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a><<a href="#Bin">Bin</a>></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>bins</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a><<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>>)</code> Array of requested bins - each object should have
<code>width</code>
,
<code>height</code>
(or
<code>w</code>
,
<code>h</code>
) properties
</div>
<table class='mt1 mb2 fixed-table h5'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<td>Name</td>
<td>Description</td>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>bins[].w</span> <code class='quiet'><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a></code>
</td>
<td class='break-word'><span>Requested bin width
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>bins[].h</span> <code class='quiet'><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a></code>
</td>
<td class='break-word'><span>Requested bin height
</span></td>
</tr>
</tbody>
</table>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>([<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>])</code>
</div>
<table class='mt1 mb2 fixed-table h5'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<td>Name</td>
<td>Description</td>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.inPlace</span> <code class='quiet'>[<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a>]</code>
(default <code>false</code>)
</td>
<td class='break-word'><span>If
<code>true</code>
, the supplied bin objects will be updated inplace with
<code>x</code>
and
<code>y</code>
properties
</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a><<a href="#Bin">Bin</a>></code>:
Array of allocated Bins - each Bin is an object with
<code>id</code>
,
<code>x</code>
,
<code>y</code>
,
<code>w</code>
,
<code>h</code>
properties
<div class='py1 quiet mt1 prose-big'>Example</div>
<pre class='p1 overflow-auto round fill-light'><span class="hljs-keyword">var</span> bins = [
{ id: <span class="hljs-number">1</span>, w: <span class="hljs-number">12</span>, h: <span class="hljs-number">12</span> },
{ id: <span class="hljs-number">2</span>, w: <span class="hljs-number">12</span>, h: <span class="hljs-number">16</span> },
{ id: <span class="hljs-number">3</span>, w: <span class="hljs-number">12</span>, h: <span class="hljs-number">24</span> }
];
<span class="hljs-keyword">var</span> results = sprite.pack(bins, { inPlace: <span class="hljs-literal">false</span> });</pre>
</section>
</div>
</div>
<div class='keyline-bottom' id='ShelfPack#packOne'>
<div class="clearfix small pointer toggle-sibling">
<div class="pad1y contain">
<a class='icon pin-right pad1y dark-link caret-right'></a>
<span class='code strong strong truncate'>packOne</span>
<span class='quiet code space-right2'>(w, h, [id])</span>
</div>
</div>
<div class="clearfix hidden toggle-target">
<section class='py2 clearfix'>
<p>Pack a single bin into the sprite.</p>
<p>Each bin will have a unique identitifer.
If no identifier is supplied in the <code>id</code> parameter, one will be created.
Note: The supplied <code>id</code> is used as an object index, so numeric values are fastest!</p>
<p>Bins are automatically refcounted (i.e. a newly packed Bin will have a refcount of 1).
When a bin is no longer needed, use the <code>ShelfPack.unref</code> function to mark it
as unused. When a Bin's refcount decrements to 0, the Bin will be marked
as free and its space may be reused by the packing code.</p>
<div class='pre p1 fill-light'>packOne(w: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>, h: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>, id: [(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>)]): <a href="#Bin">Bin</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>w</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)</code> Width of the bin to allocate
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>h</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)</code> Height of the bin to allocate
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>id</span> <code class='quiet'>([(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>)])</code> Unique identifier for this bin, (if unsupplied, assume it's a new bin and create an id)
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="#Bin">Bin</a></code>:
Bin object with
<code>id</code>
,
<code>x</code>
,
<code>y</code>
,
<code>w</code>
,
<code>h</code>
properties, or
<code>null</code>
if allocation failed
<div class='py1 quiet mt1 prose-big'>Example</div>
<pre class='p1 overflow-auto round fill-light'><span class="hljs-keyword">var</span> results = sprite.packOne(<span class="hljs-number">12</span>, <span class="hljs-number">16</span>, <span class="hljs-string">'a'</span>);</pre>
</section>
</div>
</div>
<div class='keyline-bottom' id='ShelfPack#getBin'>
<div class="clearfix small pointer toggle-sibling">
<div class="pad1y contain">
<a class='icon pin-right pad1y dark-link caret-right'></a>
<span class='code strong strong truncate'>getBin</span>
<span class='quiet code space-right2'>(id)</span>
</div>
</div>
<div class="clearfix hidden toggle-target">
<section class='py2 clearfix'>
<p>Return a packed bin given its id, or undefined if the id is not found</p>
<div class='pre p1 fill-light'>getBin(id: (<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>)): <a href="#Bin">Bin</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>id</span> <code class='quiet'>((<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>))</code> Unique identifier for this bin,
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="#Bin">Bin</a></code>:
The requested bin, or undefined if not yet packed
<div class='py1 quiet mt1 prose-big'>Example</div>
<pre class='p1 overflow-auto round fill-light'><span class="hljs-keyword">var</span> b = sprite.getBin(<span class="hljs-string">'a'</span>);</pre>
</section>
</div>
</div>
<div class='keyline-bottom' id='ShelfPack#ref'>
<div class="clearfix small pointer toggle-sibling">
<div class="pad1y contain">
<a class='icon pin-right pad1y dark-link caret-right'></a>
<span class='code strong strong truncate'>ref</span>
<span class='quiet code space-right2'>(bin)</span>
</div>
</div>
<div class="clearfix hidden toggle-target">
<section class='py2 clearfix'>
<p>Increment the ref count of a bin and update statistics.</p>
<div class='pre p1 fill-light'>ref(bin: Bin): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>bin</span> <code class='quiet'>(<a href="#Bin">Bin</a>)</code> Bin instance
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a></code>:
New refcount of the bin
<div class='py1 quiet mt1 prose-big'>Example</div>
<pre class='p1 overflow-auto round fill-light'><span class="hljs-keyword">var</span> bin = sprite.getBin(<span class="hljs-string">'a'</span>);
sprite.ref(bin);</pre>
</section>
</div>
</div>
<div class='keyline-bottom' id='ShelfPack#unref'>
<div class="clearfix small pointer toggle-sibling">
<div class="pad1y contain">
<a class='icon pin-right pad1y dark-link caret-right'></a>
<span class='code strong strong truncate'>unref</span>
<span class='quiet code space-right2'>(bin)</span>
</div>
</div>
<div class="clearfix hidden toggle-target">
<section class='py2 clearfix'>
<p>Decrement the ref count of a bin and update statistics.
The bin will be automatically marked as free space once the refcount reaches 0.</p>
<div class='pre p1 fill-light'>unref(bin: Bin): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>bin</span> <code class='quiet'>(<a href="#Bin">Bin</a>)</code> Bin instance
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a></code>:
New refcount of the bin
<div class='py1 quiet mt1 prose-big'>Example</div>
<pre class='p1 overflow-auto round fill-light'><span class="hljs-keyword">var</span> bin = sprite.getBin(<span class="hljs-string">'a'</span>);
sprite.unref(bin);</pre>
</section>
</div>
</div>
<div class='keyline-bottom' id='ShelfPack#clear'>
<div class="clearfix small pointer toggle-sibling">
<div class="pad1y contain">
<a class='icon pin-right pad1y dark-link caret-right'></a>
<span class='code strong strong truncate'>clear</span>
<span class='quiet code space-right2'>()</span>
</div>
</div>
<div class="clearfix hidden toggle-target">
<section class='py2 clearfix'>
<p>Clear the sprite. Resets everything and resets statistics.</p>
<div class='pre p1 fill-light'>clear()</div>
<div class='py1 quiet mt1 prose-big'>Example</div>
<pre class='p1 overflow-auto round fill-light'>sprite.clear();</pre>
</section>
</div>
</div>
<div class='keyline-bottom' id='ShelfPack#resize'>
<div class="clearfix small pointer toggle-sibling">
<div class="pad1y contain">
<a class='icon pin-right pad1y dark-link caret-right'></a>
<span class='code strong strong truncate'>resize</span>
<span class='quiet code space-right2'>(w, h)</span>
</div>
</div>
<div class="clearfix hidden toggle-target">
<section class='py2 clearfix'>
<p>Resize the sprite.</p>
<div class='pre p1 fill-light'>resize(w: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>, h: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>w</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)</code> Requested new sprite width
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>h</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)</code> Requested new sprite height
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></code>:
<code>true</code>
if resize succeeded,
<code>false</code>
if failed
<div class='py1 quiet mt1 prose-big'>Example</div>
<pre class='p1 overflow-auto round fill-light'>sprite.resize(<span class="hljs-number">256</span>, <span class="hljs-number">256</span>);</pre>
</section>
</div>
</div>
</div>
</section>
<section class='py2 clearfix'>
<div class='clearfix'>
<h2 class='fl' id='Bin'>
Bin
</h2>
<a class='fr fill-darken0 round round pad1x quiet h5' href='https://github.com/mapbox/shelf-pack/blob/1da2aaf1600a242fc36c5a3ad2b2b9fda0092182/index.js#L428-L437'>
<span>index.js</span>
</a>
</div>
<p>Create a new Bin object.</p>
<div class='pre p1 fill-light'>Bin(id: (<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>), x: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>, y: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>, w: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>, h: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>id</span> <code class='quiet'>((<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>))</code> Unique id of the bin
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>x</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)</code> Left coordinate of the bin
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>y</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)</code> Top coordinate of the bin
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>w</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)</code> Width of the bin
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>h</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>)</code> Height of the bin
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Example</div>
<pre class='p1 overflow-auto round fill-light'><span class="hljs-keyword">var</span> bin = <span class="hljs-keyword">new</span> Bin(<span class="hljs-string">'a'</span>, <span class="hljs-number">0</span>, <span class="hljs-number">0</span>, <span class="hljs-number">12</span>, <span class="hljs-number">16</span>);</pre>
</section>
</div>
</div>
</div>
</div>
<script src='assets/anchor.js'></script>
<script src='assets/site.js'></script>
</body>
</html>