Mesa (master): pp: Docs

[Brian Paul]

Module: Mesa
Branch: master
Commit: e86e4cf128105db8b3e18d34b28040a26be6516c
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=e86e4cf128105db8b3e18d34b28040a26be6516c

Author: Lauri Kasanen <cand at gmx.com>
Date:   Thu Aug 18 10:22:12 2011 +0300

pp: Docs

Signed-off-by: Lauri Kasanen <cand at gmx.com>
Signed-off-by: Brian Paul <brianp at vmware.com>

---

 src/gallium/auxiliary/postprocess/ADDING |   87 ++++++++++++++++++++++++++++++
 1 files changed, 87 insertions(+), 0 deletions(-)

diff --git a/src/gallium/auxiliary/postprocess/ADDING b/src/gallium/auxiliary/postprocess/ADDING
new file mode 100644
index 0000000..3735835
--- /dev/null
+++ b/src/gallium/auxiliary/postprocess/ADDING
@@ -0,0 +1,87 @@
+How to add a new post-processing filter
+=======================================
+
+The Gallium post-processing queue works by passing the current screen to a fragment shader.
+These shaders may be written in any supported language, but are added here in TGSI text
+assembly.
+
+You can translate GLSL/ARB fairly easily via llvmpipe (LP_DEBUG=tgsi). I don't know the
+status of the D3D state tracker, but if/when that works, I'd assume HLSL would be possible
+too.
+
+
+
+Steps
+=====
+
+1. Add it to PP
+2. Make it known to PP
+3. Make it known to driconf
+4. ????
+5. Profit
+
+
+
+
+1. Add it to PP
+---------------
+
+Once you have the shader(s) in TGSI asm, put them to static const char arrays in a header
+file (see pp_colors.h).
+
+Add the filter's prototypes (main and init functions) to postprocess.h. This is mostly a
+copy-paste job with only changing the name.
+
+Then create a file containing empty main and init functions, named as you specified above.
+See pp_colors.c for an example.
+
+
+
+2. Make it known to PP
+----------------------
+
+Add your filter to filters.h, in a correct place. Placement is important, AA should usually
+be the last effect in the queue for example.
+
+Name is the config option your filter will be enabled by, both in driconf and as an env var.
+
+Inner temp means an intermediate framebuffer you may use in your filter to store
+results between passes. If you have a single-pass filter, request 0 of those.
+
+Shaders is the number of shaders your filter needs. The minimum is 2.
+
+
+You could also write the init and main functions now. If your filter is single-pass without
+a vertex shader and any other input than the main screen, you can use pp_nocolor as your
+main function as is.
+
+
+
+3. Make it known to driconf
+---------------------------
+
+First time outside of auxiliary/postprocess. First, add a suitable description to
+drivers/dri/common/xmlpool/t_options.h, and regenerate options.h by running make in that
+directory. Use the name you put into filters.h as the config option name.
+
+With driconf aware of the option, make Gallium aware of it too. Add it to
+state_trackers/dri/common/dri_screen.c in a proper section, specifying its default value and
+the accepted range (if applicable).
+
+Do check that __driNConfigOptions is still correct after the addition.
+
+
+
+4. ????
+-------
+
+Testing, praying, hookers, blow, sacrificial lambs...
+
+
+
+5. Profit
+---------
+
+Assuming you got here, sharing is caring. Send your filter to mesa-dev.
+
+