doc: Add framebuffer docs.

* doc/api.texi (Framebuffers): Add basic API documentation.

1 files changed, 38 insertions, 0 deletions

diff --git a/doc/api.texi b/doc/api.texi
index 8295b38..694a236 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -926,6 +926,44 @@ considered an advanced feature.
 @node Framebuffers
 @subsection Framebuffers
 
+A framebuffer is a chunk of memory that the GPU can render things
+onto.  By default, the framebuffer that is used for rendering is the
+one belonging to the game window, but custom framebuffers can be used
+as well.  A common use-case for custom framebuffers is applying
+post-processing effects: The entire scene is rendered to a
+framebuffer, and then the contents of that framebuffer are applied to
+a post-processing shader and rendered to the game window.  The
+post-processing shader could do any number of things: scaling,
+antialiasing, motion blur, etc.
+
+@deffn {Procedure} make-framebuffer @var{width} @var{height} [#:min-filter 'linear] [#:mag-filter 'linear] [#:wrap-s 'repeat] [#:wrap-t 'repeat]
+
+Create a new framebuffer that is @var{width} pixels wide and @var{height} pixels high.
+
+@var{min-filter} and @var{mag-filter} determine the scaling algorithm
+applied to the framebuffer when rendering.  By default, linear scaling
+is used in both cases. To perform no smoothing at all, use
+@code{nearest} for simple nearest neighbor scaling.  This is typically
+the best choice for pixel art games.
+@end deffn
+
+@deffn {Procedure} framebuffer? @var{obj}
+Return @code{#t} if @var{obj} is a framebuffer.
+@end deffn
+
+@deffn {Procedure} framebuffer-texture @var{fb}
+Return the texture backing the framebuffer @var{fb}.
+@end deffn
+
+@deffn {Procedure} framebuffer-viewport @var{fb}
+Return the default viewport (@pxref{Viewports}) used by the
+framebuffer @var{fb}.
+@end deffn
+
+@deffn {Procedure} null-framebuffer
+The default framebuffer.
+@end deffn
+
 @node Viewports
 @subsection Viewports