# HG changeset patch
# User Mike Miller <mtmiller@ieee.org>
# Date 1366840399 14400
# Node ID 34a9a4e48f9b8dbf24f484ac6f918bc363b31ec3
# Parent  fb8fe0ed4bbb4c7426103f6958f57190ec7ec691
New function waterfall

* waterfall.m: New file.
* scripts/plot/module.mk (plot_FCN_FILES): Add it to the list.
* __unimplemented__.m (missing_functions): Remove waterfall from the list.
* plot.txi: Include waterfall docstring.
* NEWS: Mention waterfall.

diff --git a/NEWS b/NEWS
--- a/NEWS
+++ b/NEWS
@@ -178,9 +178,9 @@
 
  ** Other new functions added in 3.8.0:
 
-      betaincinv   dawson     fminsearch  polyeig     strjoin
-      cmpermute    erfcinv    importdata  rgbplot     tetramesh
-      cmunique     erfi       iscolormap  shrinkfaces
+      betaincinv   dawson     fminsearch  polyeig      strjoin
+      cmpermute    erfcinv    importdata  rgbplot      tetramesh
+      cmunique     erfi       iscolormap  shrinkfaces  waterfall
       colorcube    findfigs   lines       splinefit
 
  ** Deprecated functions.
diff --git a/doc/interpreter/plot.txi b/doc/interpreter/plot.txi
--- a/doc/interpreter/plot.txi
+++ b/doc/interpreter/plot.txi
@@ -392,6 +392,8 @@
 
 @DOCSTRING(scatter3)
 
+@DOCSTRING(waterfall)
+
 @menu
 * Aspect Ratio::
 * Three-dimensional Function Plotting::  
diff --git a/scripts/help/__unimplemented__.m b/scripts/help/__unimplemented__.m
--- a/scripts/help/__unimplemented__.m
+++ b/scripts/help/__unimplemented__.m
@@ -402,7 +402,6 @@
   "visdiff",
   "volumebounds",
   "waitfor",
-  "waterfall",
   "wavfinfo",
   "wavplay",
   "wavrecord",
diff --git a/scripts/plot/module.mk b/scripts/plot/module.mk
--- a/scripts/plot/module.mk
+++ b/scripts/plot/module.mk
@@ -204,6 +204,7 @@
   plot/view.m \
   plot/waitbar.m \
   plot/waitforbuttonpress.m \
+  plot/waterfall.m \
   plot/whitebg.m \
   plot/xlabel.m \
   plot/xlim.m \
diff --git a/scripts/plot/waterfall.m b/scripts/plot/waterfall.m
new file mode 100644
--- /dev/null
+++ b/scripts/plot/waterfall.m
@@ -0,0 +1,61 @@
+## Copyright (C) 2013 Mike Miller
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or (at
+## your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn  {Function File} {} waterfall (@var{x}, @var{y}, @var{z})
+## @deftypefnx {Function File} {} waterfall (@var{z})
+## @deftypefnx {Function File} {@var{h} =} waterfall (@dots{})
+## Plot a waterfall plot given matrices @var{x}, and @var{y} from
+## @code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and
+## @var{y} coordinates of the mesh.  If @var{x} and @var{y} are vectors,
+## then a typical vertex is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus,
+## columns of @var{z} correspond to different @var{x} values and rows of
+## @var{z} correspond to different @var{y} values.
+##
+## The optional return value @var{h} is a graphics handle to the created
+## surface object.
+## @seealso{meshgrid, meshz, surf}
+## @end deftypefn
+
+## Author: Mike Miller <mtmiller@ieee.org>
+
+function h = waterfall (varargin)
+
+  tmp = meshz (varargin{:});
+
+  set (tmp, "meshstyle", "row");
+
+  ## The gnuplot toolkit does nothing with the meshstyle property currently.
+  toolkit = get (ancestor (tmp, "figure"), "__graphics_toolkit__");
+  if (strcmp (toolkit, "gnuplot"))
+    warning ("waterfall: may not render correctly using toolkit '%s'", toolkit);
+  endif
+
+  if (nargout > 0)
+    h = tmp;
+  endif
+
+endfunction
+
+
+%!demo
+%! clf;
+%! colormap ('default');
+%! [~,~,Z] = peaks ();
+%! waterfall (Z);
+