added stb, more binaryout changes"
[henge/apc.git] / stb / README.md
diff --git a/stb/README.md b/stb/README.md
new file mode 100644 (file)
index 0000000..c22b270
--- /dev/null
@@ -0,0 +1,137 @@
+<!---   THIS FILE IS AUTOMATICALLY GENERATED, DO NOT CHANGE IT BY HAND   --->
+
+stb
+===
+
+single-file public domain libraries for C/C++ <a name="stb_libs"></a>
+
+Most libraries by stb, except: stb_dxt by Fabian "ryg" Giesen, stb_image_resize
+by Jorge L. "VinoBS" Rodriguez, and stb_sprintf by Jeff Roberts.
+
+
+library    | lastest version | category | LoC | description
+--------------------- | ---- | -------- | --- | --------------------------------
+**[stb_vorbis.c](stb_vorbis.c)** | 1.09 | audio | 5399 | decode ogg vorbis files from file/memory to float/16-bit signed output
+**[stb_image.h](stb_image.h)** | 2.14 | graphics | 7102 | image loading/decoding from file/memory: JPG, PNG, TGA, BMP, PSD, GIF, HDR, PIC
+**[stb_truetype.h](stb_truetype.h)** | 1.14 | graphics | 4018 | parse, decode, and rasterize characters from truetype fonts
+**[stb_image_write.h](stb_image_write.h)** | 1.03 | graphics | 1049 | image writing to disk: PNG, TGA, BMP
+**[stb_image_resize.h](stb_image_resize.h)** | 0.92 | graphics | 2580 | resize images larger/smaller with good quality
+**[stb_rect_pack.h](stb_rect_pack.h)** | 0.10 | graphics | 583 | simple 2D rectangle packer with decent quality
+**[stb_sprintf.h](stb_sprintf.h)** | 1.02 | utility | 1087 | fast sprintf, snprintf for C/C++
+**[stretchy_buffer.h](stretchy_buffer.h)** | 1.02 | utility | 216 | typesafe dynamic array for C (i.e. approximation to vector<>), doesn't compile as C++
+**[stb_textedit.h](stb_textedit.h)** | 1.10 | user&nbsp;interface | 1330 | guts of a text editor for games etc implementing them from scratch
+**[stb_voxel_render.h](stb_voxel_render.h)** | 0.84 | 3D&nbsp;graphics | 3752 | Minecraft-esque voxel rendering "engine" with many more features
+**[stb_dxt.h](stb_dxt.h)** | 1.04 | 3D&nbsp;graphics | 630 | Fabian "ryg" Giesen's real-time DXT compressor
+**[stb_perlin.h](stb_perlin.h)** | 0.2 | 3D&nbsp;graphics | 182 | revised Perlin noise (3D input, 1D output)
+**[stb_easy_font.h](stb_easy_font.h)** | 1.0 | 3D&nbsp;graphics | 263 | quick-and-dirty easy-to-deploy bitmap font for printing frame rate, etc
+**[stb_tilemap_editor.h](stb_tilemap_editor.h)** | 0.38 | game&nbsp;dev | 4132 | embeddable tilemap editor
+**[stb_herringbone_wa...](stb_herringbone_wang_tile.h)** | 0.6 | game&nbsp;dev | 1220 | herringbone Wang tile map generator
+**[stb_c_lexer.h](stb_c_lexer.h)** | 0.08 | parsing | 820 | simplify writing parsers for C-like languages
+**[stb_divide.h](stb_divide.h)** | 0.91 | math | 379 | more useful 32-bit modulus e.g. "euclidean divide"
+**[stb_connected_comp...](stb_connected_components.h)** | 0.95 | misc | 1006 | incrementally compute reachability on grids
+**[stb.h](stb.h)** | 2.28 | misc | 14277 | helper functions for C, mostly redundant in C++; basically author's personal stuff
+**[stb_leakcheck.h](stb_leakcheck.h)** | 0.3 | misc | 124 | quick-and-dirty malloc/free leak-checking
+
+Total libraries: 20  
+Total lines of C code: 50149
+
+
+FAQ
+---
+
+#### What's the license?
+
+These libraries are in the public domain (or the equivalent where that is not
+possible). You can do anything you want with them. You have no legal obligation
+to do anything else, although I appreciate attribution.
+
+#### <a name="other_libs"></a> Are there other single-file public-domain/open source libraries with minimal dependencies out there?
+
+[Yes.](https://github.com/nothings/single_file_libs)
+
+#### If I wrap an stb library in a new library, does the new library have to be public domain?
+
+No.
+
+#### Some of these libraries seem redundant to existing open source libraries. Are they better somehow?
+
+Generally they're only better in that they're easier to integrate,
+easier to use, and easier to release (single file; good API; no
+attribution requirement). They may be less featureful, slower,
+and/or use more memory. If you're already using an equivalent
+library, there's probably no good reason to switch.
+
+###### Can I link directly to the table of stb libraries?
+
+You can use [this URL](https://github.com/nothings/stb#stb_libs) to link directly to that list.
+
+#### Why do you list "lines of code"? It's a terrible metric.
+
+Just to give you some idea of the internal complexity of the library,
+to help you manage your expectations, or to let you know what you're
+getting into. While not all the libraries are written in the same
+style, they're certainly similar styles, and so comparisons between
+the libraries are probably still meaningful.
+
+Note though that the lines do include both the implementation, the
+part that corresponds to a header file, and the documentation.
+
+#### Why single-file headers?
+
+Windows doesn't have standard directories where libraries
+live. That makes deploying libraries in Windows a lot more
+painful than open source developers on Unix-derivates generally
+realize. (It also makes library dependencies a lot worse in Windows.)
+
+There's also a common problem in Windows where a library was built
+against a different version of the runtime library, which causes
+link conflicts and confusion. Shipping the libs as headers means
+you normally just compile them straight into your project without
+making libraries, thus sidestepping that problem.
+
+Making them a single file makes it very easy to just
+drop them into a project that needs them. (Of course you can
+still put them in a proper shared library tree if you want.)
+
+Why not two files, one a header and one an implementation?
+The difference between 10 files and 9 files is not a big deal,
+but the difference between 2 files and 1 file is a big deal.
+You don't need to zip or tar the files up, you don't have to
+remember to attach *two* files, etc.
+
+#### Why "stb"? Is this something to do with Set-Top Boxes?
+
+No, they are just the initials for my name, Sean T. Barrett.
+This was not chosen out of egomania, but as a moderately sane
+way of namespacing the filenames and source function names.
+
+#### Will you add more image types to stb_image.h?
+
+If people submit them, I generally add them, but the goal of stb_image
+is less for applications like image viewer apps (which need to support
+every type of image under the sun) and more for things like games which
+can choose what images to use, so I may decline to add them if they're
+too rare or if the size of implementation vs. apparent benefit is too low.
+
+#### Do you have any advice on how to create my own single-file library?
+
+Yes. https://github.com/nothings/stb/blob/master/docs/stb_howto.txt
+
+#### Why public domain?
+
+I prefer it over GPL, LGPL, BSD, zlib, etc. for many reasons.
+Some of them are listed here:
+https://github.com/nothings/stb/blob/master/docs/why_public_domain.md
+
+#### Why C?
+
+Primarily, because I use C, not C++. But it does also make it easier
+for other people to use them from other languages.
+
+#### Why not C99? stdint.h, declare-anywhere, etc.
+
+I still use MSVC 6 (1998) as my IDE because it has better human factors
+for me than later versions of MSVC.
+
+
+