1HEADmaster

4 files changed, 475 insertions, 0 deletions

diff --git a/thirdparty/stb/docs/other_libs.md b/thirdparty/stb/docs/other_libs.md
new file mode 100644
index 0000000..62f379c
--- /dev/null
+++ b/thirdparty/stb/docs/other_libs.md
@@ -0,0 +1 @@
+Moved to https://github.com/nothings/single_file_libs
\ No newline at end of file
diff --git a/thirdparty/stb/docs/stb_howto.txt b/thirdparty/stb/docs/stb_howto.txt
new file mode 100644
index 0000000..a969b54
--- /dev/null
+++ b/thirdparty/stb/docs/stb_howto.txt
@@ -0,0 +1,185 @@
+Lessons learned about how to make a header-file library
+V1.0
+September 2013 Sean Barrett
+
+Things to do in an stb-style header-file library,
+and rationales:
+
+
+1. #define LIBRARYNAME_IMPLEMENTATION
+
+Use a symbol like the above to control creating
+the implementation. (I used a far-less-clear name
+in my first header-file library; it became
+clear that was a mistake once I had multiple
+libraries.)
+
+Include a "header-file" section with header-file
+guards and declarations for all the functions,
+but only guard the implementation with LIBRARYNAME_IMPLEMENTATION,
+not the header-file guard. That way, if client's
+header file X includes your header file for
+declarations, they can still include header file X
+in the source file that creates the implementation;
+if you guard the implementation too, then the first
+include (before the #define) creates the declarations,
+and the second one (after the #define) does nothing.
+
+
+2. AVOID DEPENDENCIES
+
+Don't rely on anything other than the C standard libraries.
+
+(If you're creating a library specifically to leverage/wrap
+some other library, then obviously you can rely on that
+library. But if that library is public domain, you might
+be better off directly embedding the source, to reduce
+dependencies for your clients. But of course now you have
+to update whenever that library updates.)
+
+If you use stdlib, consider wrapping all stdlib calls in
+macros, and then conditionally define those macros to the
+stdlib function, allowing the user to replace them.
+
+For functions with side effects, like memory allocations,
+consider letting the user pass in a context and pass
+that in to the macros. (The stdlib versions will ignore
+the parameter.) Otherwise, users may have to use global
+or thread-local variables to achieve the same effect.
+
+
+3. AVOID MALLOC
+
+You can't always do this, but when you can, embedded developers
+will appreciate it. I almost never bother avoiding, as it's
+too much work (and in some cases is pretty infeasible;
+see http://nothings.org/gamedev/font_rendering_malloc.txt ).
+But it's definitely something one of the things I've gotten
+the most pushback on from potential users.
+
+
+4. ALLOW STATIC IMPLEMENTATION
+
+Have a #define which makes function declarations and
+function definitions static. This makes the implementation
+private to the source file that creates it. This allows
+people to use your library multiple times in their project
+without collision. (This is only necessary if your library
+has configuration macros or global state, or if your
+library has multiple versions that are not backwards
+compatible. I've run into both of those cases.)
+
+
+5. MAKE ACCESSIBLE FROM C
+
+Making your code accessible from C instead of C++ (i.e.
+either coding in C, or using extern "C") makes it more
+straightforward to be used in C and in other languages,
+which often only have support for C bindings, not C++.
+(One of the earliest results I found in googling for
+stb_image was a Haskell wrapper.) Otherwise, people
+have to wrap it in another set of function calls, and
+the whole point here is to make it convenient for people
+to use, isn't it? (See below.)
+
+I prefer to code entirely in C, so the source file that
+instantiates the implementation can be C itself, for
+those crazy people out there who are programming in C.
+But it's probably not a big hardship for a C programmer
+to create a single C++ source file to instantiate your
+library.
+
+
+6. NAMESPACE PRIVATE FUNCTIONS
+
+Try to avoid having names in your source code that
+will cause conflicts with identical names in client
+code. You can do this either by namespacing in C++,
+or prefixing with your library name in C.
+
+In C, generally, I use the same prefix for API
+functions and private symbols, such as "stbtt_"
+for stb_truetype; but private functions (and
+static globals) use a second underscore as
+in "stbtt__" to further minimize the chance of
+additional collisions in the unlikely but not
+impossible event that users write wrapper
+functions that have names of the form "stbtt_".
+(Consider the user that has used "stbtt_foo"
+*successfully*, and then upgrades to a new
+version of your library which has a new private
+function named either "stbtt_foo" or "stbtt__foo".)
+
+Note that the double-underscore is reserved for
+use by the compiler, but (1) there is nothing
+reserved for "middleware", i.e. libraries
+desiring to avoid conflicts with user symbols
+have no other good options, and (2) in practice
+no compilers use double-underscore in the middle
+rather than the beginning/end. (Unfortunately,
+there is at least one videogame-console compiler that
+will warn about double-underscores by default.)
+
+
+7. EASY-TO-COMPLY LICENSE
+
+I make my libraries public domain. You don't have to.
+But my goal in releasing stb-style libraries is to
+reduce friction for potential users as much as
+possible. That means:
+
+    a. easy to build (what this file is mostly about)
+    b. easy to invoke (which requires good API design)
+    c. easy to deploy (which is about licensing)
+
+I choose to place all my libraries in the public
+domain, abjuring copyright, rather than license
+the libraries. This has some benefits and some
+drawbacks.
+
+Any license which is "viral" to modifications
+causes worries for lawyers, even if their programmers
+aren't modifying it.
+
+Any license which requires crediting in documentation
+adds friction which can add up. Valve used to have
+a page with a list of all of these on their web site,
+and it was insane, and obviously nobody ever looked
+at it so why would you care whether your credit appeared
+there?
+
+Permissive licenses like zlib and BSD license are
+perfectly reasonable, but they are very wordy and
+have only two benefits over public domain: legally-mandated
+attribution and liability-control. I do not believe these
+are worth the excessive verbosity and user-unfriendliness
+these licenses induce, especially in the single-file
+case where those licenses tend to be at the top of
+the file, the first thing you see. (To the specific
+points, I have had no trouble receiving attribution
+for my libraries; liability in the face of no explicit
+disclaimer of liability is an open question.)
+
+However, public domain has frictions of its own, because
+public domain declarations aren't necessary recognized
+in the USA and some other locations. For that reason,
+I recommend a declaration along these lines:
+
+// This software is dual-licensed to the public domain and under the following
+// license: you are granted a perpetual, irrevocable license to copy, modify,
+// publish, and distribute this file as you see fit.
+
+I typically place this declaration at the end of the initial
+comment block of the file and just say 'public domain'
+at the top.
+
+I have had people say they couldn't use one of my
+libraries because it was only "public domain" and didn't
+have the additional fallback clause, who asked if
+I could dual-license it under a traditional license.
+
+My answer: they can create a derivative work by
+modifying one character, and then license that however
+they like. (Indeed, *adding* the zlib or BSD license
+would be such a modification!) Unfortunately, their
+lawyers reportedly didn't like that answer. :(
diff --git a/thirdparty/stb/docs/stb_voxel_render_interview.md b/thirdparty/stb/docs/stb_voxel_render_interview.md
new file mode 100644
index 0000000..7071466
--- /dev/null
+++ b/thirdparty/stb/docs/stb_voxel_render_interview.md
@@ -0,0 +1,173 @@
+# An interview with STB about stb_voxel_render.h
+
+**Q:**
+I suppose you really like Minecraft?
+
+**A:**
+Not really. I mean, I do own it and play it some, and
+I do watch YouTube videos of other people playing it
+once in a while, but I'm not saying it's that great.
+
+But I do love voxels. I've been playing with voxel rendering
+since the mid-late 90's when we were still doing software
+rendering and thinking maybe polygons weren't the answer.
+Once GPUs came along that kind of died off, at least until
+Minecraft brought it back to attention.
+
+**Q:**
+Do you expect people will make a lot of Minecraft clones
+with this?
+
+**A:**
+I hope not!
+
+For one thing, it's a terrible idea for the
+developer. Remember before Minecraft was on the Xbox 360,
+there were a ton of "indie" clones (some maybe making
+decent money even), but then the real Minecraft came out
+and just crushed them (as far as I know). It's just not
+something you really want to compete with.
+
+The reason I made this library is because I'd like
+to see more games with Minecraft's *art style*, not
+necessary its *gameplay*.
+
+I can understand the urge to clone the gameplay. When
+you have a world made of voxels/blocks, there are a
+few things that become incredibly easy to do that would
+otherwise be very hard (at least for an indie) to do in 3D.
+One thing is that procedural generation becomes much easier.
+Another is that destructible environments are easy. Another
+is that you have a world where your average user can build
+stuff that they find satisfactory.
+
+Minecraft is at a sort of local maximum, a sweet spot, where
+it leverages all of those easy-to-dos. And so I'm sure it's
+hard to look at the space of 'games using voxels' and move
+away from that local maximum, to give up some of that.
+But I think that's what people should do.
+
+**Q:**
+So what else can people do with stb_voxel_render?
+
+**A:**
+All of those benefits I mentioned above are still valid even
+if you stay away from the sweet spot. You can make a 3D roguelike
+without player-creation/destruction that uses procedural generation.
+You could make a shooter with pre-designed maps but destructible
+environments.
+
+And I'm sure there are other possible benefits to using voxels/blocks.
+Hopefully this will make it easier for people to explore the space.
+
+The library has a pretty wide range of features to allow
+people to come up with some distinctive looks. For example,
+the art style of Continue?9876543210 was one of the inspirations
+for trying to make the multitexturing capabilities flexible.
+I'm terrible at art, so this isn't really something I can
+come up with myself, but I tried to put in flexible
+technology that could be used multiple ways.
+
+One thing I did intentionally was try to make it possible to
+make nicer looking ground terrain, using the half-height
+slopes and "weird slopes". There are Minecraft mods with
+drivable cars and they just go up these blocky slopes and,
+like, what? So I wanted you to be able to make smoother
+terrain, either just for the look, or for vehicles etc.
+Also, you can spatially cross-fade between two ground textures for
+that classic bad dirt/grass transition that has shipped
+in plenty of professional games. Of course, you could
+just use a separate non-voxel ground renderer for all of
+this. But this way, you can seamlessly integrate everything
+else with it. E.g. in your authoring tool (or procedural
+generation) you can make smooth ground and then cut a
+sharp-edged hole in it for a building's basement or whatever.
+
+Another thing you can do is work at a very different scale.
+In Minecraft, a person is just under 2 blocks tall. In
+Ace of Spades, a person is just under 3 blocks tall. Why
+not 4 or 6? Well, partly because you just need a lot more
+voxels; if a meter is 2 voxels in Mineraft and 4 voxels in
+your game, and you draw the same number of voxels due to
+hardware limits, then your game has half the view distance
+of Minecraft. Since stb_voxel_render is designed to keep
+the meshes small and render efficiently, you can push the
+view distance out further than Minecraft--or use a similar
+view distance and a higher voxel resolution. You could also
+stop making infinite worlds and work at entirely different
+scales; where Minecraft is 1 voxel per meter, you could
+have 20 voxels per meter and make a small arena that's
+50 meters wide and 5 meters tall.
+
+Back when the voxel game Voxatron was announced, the weekend
+after the trailer came out I wrote my own little GPU-accelerated
+version of the engine and thought that was pretty cool. I've
+been tempted many times to extract that and release it
+as a library, but
+I don't want to steal Voxatron's thunder so I've avoided
+it. You could use this engine to do the same kind of thing,
+although it won't be as efficient as an engine dedicated to
+that style of thing would be.
+
+**Q:**
+What one thing would you really like to see somebody do?
+
+**A:**
+Before Unity, 3D has seemed deeply problematic in the indie
+space. Software like GameMaker has tried to support 3D but
+it seems like little of note has been done with it.
+
+Minecraft has shown that people can build worlds with the
+Minecraft toolset far more easily than we've ever seen from those
+other tools. Obviously people have done great things with
+Unity, but those people are much closer to professional
+developers; typically they still need real 3D modelling
+and all of that stuff.
+
+So what I'd really like to see is someone build some kind
+of voxel-game-construction-set. Start with stb_voxel_render,
+maybe expose all the flexibility of stb_voxel_render (so
+people can do different things). Thrown in lua or something
+else for scripting, make some kind of editor that feels
+at least as good as Minecraft and Infinifactory, and see
+where that gets you.
+
+**Q:**
+Why'd you make this library?
+
+**A:**
+Mainly as a way of releasing this technology I've been working
+on since 2011 and seemed unlikely to ever ship myself. In 2011
+I was playing the voxel shooter Ace of Spades. One of the maps
+that we played on was a partial port of Broville (which is the
+first Minecraft map in stb_voxel_render release trailer). I'd
+made a bunch of procedural level generators for the game, and
+I started trying to make a city generator inspired by Broville.
+
+But I realized it would be a lot of work, and of very little
+value (most of my maps didn't get much play because people
+preferred to play on maps where they could charge straight
+at the enemies and shoot them as fast as possible). So I
+wrote my own voxel engine and started working on a procedural
+city game. But I got bogged down after I finally got the road
+generator working and never got anywhere with building
+generation or gameplay.
+
+stb_voxel_render is actually a complete rewrite from scratch,
+but it's based a lot on what I learned from that previous work.
+
+**Q:**
+About the release video... how long did that take to edit?
+
+**A:**
+About seven or eight hours. I had the first version done in
+maybe six or seven hours, but then I realized I'd left out
+one clip, and when I went back to add it I also gussied up
+a couple other moments in the video. But there was something
+basically identical to it that was done in around six.
+
+**Q:** 
+Ok, that's it. Thanks, me.
+
+**A:**
+Thanks *me!*
diff --git a/thirdparty/stb/docs/why_public_domain.md b/thirdparty/stb/docs/why_public_domain.md
new file mode 100644
index 0000000..56cef39
--- /dev/null
+++ b/thirdparty/stb/docs/why_public_domain.md
@@ -0,0 +1,116 @@
+My collected rationales for placing these libraries
+in the public domain:
+
+1. Public domain vs. viral licenses
+
+  Why is this library public domain?
+  Because more people will use it. Because it's not viral, people are
+  not obligated to give back, so you could argue that it hurts the
+  development of it, and then because it doesn't develop as well it's
+  not as good, and then because it's not as good, in the long run
+  maybe fewer people will use it. I have total respect for that
+  opinion, but I just don't believe it myself for most software.
+
+2. Public domain vs. attribution-required licenses
+
+  The primary difference between public domain and, say, a Creative Commons
+  commercial / non-share-alike / attribution license is solely the
+  requirement for attribution. (Similarly the BSD license and such.)
+  While I would *appreciate* acknowledgement and attribution, I believe
+  that it is foolish to place a legal encumberment (i.e. a license) on
+  the software *solely* to get attribution.
+
+  In other words, I'm arguing that PD is superior to the BSD license and
+  the Creative Commons 'Attribution' license. If the license offers
+  anything besides attribution -- as does, e.g., CC NonCommercial-ShareAlike,
+  or the GPL -- that's a separate discussion.
+
+3. Other aspects of BSD-style licenses besides attribution
+
+  Permissive licenses like zlib and BSD license are perfectly reasonable
+  in their requirements, but they are very wordy and
+  have only two benefits over public domain: legally-mandated
+  attribution and liability-control. I do not believe these
+  are worth the excessive verbosity and user-unfriendliness
+  these licenses induce, especially in the single-file
+  case where those licenses tend to be at the top of
+  the file, the first thing you see.
+
+  To the specific points, I have had no trouble receiving
+  attribution for my libraries; liability in the face of
+  no explicit disclaimer of liability is an open question,
+  but one I have a lot of difficulty imagining there being
+  any actual doubt about in court. Sometimes I explicitly
+  note in my libraries that I make no guarantees about them
+  being fit for purpose, but it's pretty absurd to do this;
+  as a whole, it comes across as "here is a library to decode
+  vorbis audio files, but it may not actually work and if
+  you have problems it's not my fault, but also please
+  report bugs so I can fix them"--so dumb!
+
+4. full discussion from stb_howto.txt on what YOU should do for YOUR libs
+
+```
+EASY-TO-COMPLY LICENSE
+
+I make my libraries public domain. You don't have to.
+But my goal in releasing stb-style libraries is to
+reduce friction for potential users as much as
+possible. That means:
+
+  a. easy to build (what this file is mostly about)
+  b. easy to invoke (which requires good API design)
+  c. easy to deploy (which is about licensing)
+
+I choose to place all my libraries in the public
+domain, abjuring copyright, rather than license
+the libraries. This has some benefits and some
+drawbacks.
+
+Any license which is "viral" to modifications
+causes worries for lawyers, even if their programmers
+aren't modifying it.
+
+Any license which requires crediting in documentation
+adds friction which can add up. Valve used to have
+a page with a list of all of these on their web site,
+and it was insane, and obviously nobody ever looked
+at it so why would you care whether your credit appeared
+there?
+
+Permissive licenses like zlib and BSD license are
+perfectly reasonable, but they are very wordy and
+have only two benefits over public domain: legally-mandated
+attribution and liability-control. I do not believe these
+are worth the excessive verbosity and user-unfriendliness
+these licenses induce, especially in the single-file
+case where those licenses tend to be at the top of
+the file, the first thing you see. (To the specific
+points, I have had no trouble receiving attribution
+for my libraries; liability in the face of no explicit
+disclaimer of liability is an open question.)
+
+However, public domain has frictions of its own, because
+public domain declarations aren't necessary recognized
+in the USA and some other locations. For that reason,
+I recommend a declaration along these lines:
+
+// This software is dual-licensed to the public domain and under the following
+// license: you are granted a perpetual, irrevocable license to copy, modify,
+// publish, and distribute this file as you see fit.
+
+I typically place this declaration at the end of the initial
+comment block of the file and just say 'public domain'
+at the top.
+
+I have had people say they couldn't use one of my
+libraries because it was only "public domain" and didn't
+have the additional fallback clause, who asked if
+I could dual-license it under a traditional license.
+
+My answer: they can create a derivative work by
+modifying one character, and then license that however
+they like. (Indeed, *adding* the zlib or BSD license
+would be such a modification!) Unfortunately, their
+lawyers reportedly didn't like that answer. :(
+```