cogl docs: Improve documentation for cogl_ortho

cogl_ortho is one of those APIs whos style was, for better or worse,
copied from OpenGL and for some inexplicable reason the near and far
arguments are inconsistent with the left, right, top, bottom arguments
because they don't take z coordinates they take a "distance" which
should be negative for a plane behind the viewer.

This updates the documentation to explain this.
This commit is contained in:
Robert Bragg 2010-05-26 03:07:17 +01:00
parent a5d6c02f7c
commit fca054e949
3 changed files with 21 additions and 6 deletions

View File

@ -258,13 +258,26 @@ cogl_frustum (float left,
* @right: The coordinate for the right clipping plane
* @bottom: The coordinate for the bottom clipping plane
* @top: The coordinate for the top clipping plane
* @near: The coordinate for the near clipping plane (may be negative if
* @near: The <b>distance</b> to the near clipping plane (negative if
* the plane is behind the viewer)
* @far: The coordinate for the far clipping plane (may be negative if
* @far: The <b>distance</b> for the far clipping plane (negative if
* the plane is behind the viewer)
*
* Replaces the current projection matrix with a parallel projection
* matrix.
* Replaces the current projection matrix with an orthographic projection
* matrix. See <xref linkend="cogl-ortho-matrix"/> to see how the matrix is
* calculated.
*
* <figure id="cogl-ortho-matrix">
* <title></title>
* <graphic fileref="cogl_ortho.png" format="PNG"/>
* </figure>
*
* <note>cogl_ortho copies the arguments from OpenGL's glOrtho even
* though they are unnecessarily confusing due to the z near and z far
* arguments actually being a "distance" from the origin, where
* negative values are behind the viewer, instead of coordinates for
* the z clipping planes which would have been consistent with the
* left, right bottom and top arguments.</note>
*
* Since: 1.0
*/

View File

@ -92,7 +92,8 @@ EXTRA_HFILES=
# Images to copy into HTML directory.
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
HTML_IMAGES = \
fill-rule.png
fill-rule.png \
cogl_ortho.png
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
@ -121,4 +122,5 @@ include $(top_srcdir)/gtk-doc.make
# e.g. EXTRA_DIST += version.xml.in
EXTRA_DIST += \
fill-rule.png
fill-rule.png \
cogl_ortho.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB