Finished 3D renderer doc page

collects/plot/scribblings/plot2d.scrbl

@@ -88,8 +88,8 @@ Use @(racket plot-snip) to create an @(racket image-snip%) regardless of the val
 }
 
 @doc-apply[plot/dc]{
-Plots to an arbitrary device context.
+Plots to an arbitrary device context, in the rectangle with width @(racket width), height @(racket height), and upper-left corner @(racket x),@(racket y).
-The width and height of the plot are the device context's width and height.
+
 Every @secref{plot2d} procedure is defined in terms of @(racket plot/dc).
 
 Use this if you need to continually update a plot on a @(racket canvas%), or to create other @(racket plot)-like functions with different backends.

collects/plot/scribblings/plot3d.scrbl

@@ -54,7 +54,8 @@ These procedures correspond with  @(racket plot-file), @(racket plot-pict), @(ra
 }
 
 @doc-apply[plot3d/dc]{
-Plots to an arbitrary device context. The width and height of the plot are the device context's width and height.
+Plots to an arbitrary device context, in the rectangle with width @(racket width), height @(racket height), and upper-left corner @(racket x),@(racket y).
+
 Every @secref{plot3d} procedure is defined in terms of @(racket plot3d/dc).
 
 Use this if you need to continually update a plot on a @(racket canvas%), or to create other @(racket plot3d)-like functions with different backends.

collects/plot/scribblings/renderer2d.scrbl

@@ -11,9 +11,9 @@ Returns @racket[#t] if @racket[value] is a 2D @tech{renderer}; that is, if @rack
 The following functions create such renderers.
 }
 
-@section[#:tag "renderer-function-arguments"]{2D Renderer Function Arguments}
+@section[#:tag "renderer2d-function-arguments"]{2D Renderer Function Arguments}
 
-Functions that return renderers always have these kinds of arguments:
+Functions that return 2D renderers always have these kinds of arguments:
 @itemlist[
           @item{Required (and possibly optional) arguments representing the graph to plot.}
           @item{Optional keyword arguments for overriding calculated bounds, with the default value @(racket #f).}

collects/plot/scribblings/renderer3d.scrbl

@@ -11,12 +11,23 @@ Returns @racket[#t] if @racket[value] is a 3D @tech{renderer}; that is, if @rack
 The following functions create such renderers.
 }
 
+@section[#:tag "renderer3d-function-arguments"]{3D Renderer Function Arguments}
+
+As with functions that return 2D renderers, functions that return 3D renderers always have these kinds of arguments:
+@itemlist[
+          @item{Required (and possibly optional) arguments representing the graph to plot.}
+          @item{Optional keyword arguments for overriding calculated bounds, with the default value @(racket #f).}
+          @item{Optional keyword arguments that determine the appearance of the plot.}
+          @item{The optional keyword argument @(racket #:label), which specifies the name of the renderer in the legend.}]
+
+See @secref["renderer2d-function-arguments"] for a detailed example.
+
 @section{3D Point Renderers}
 
 @doc-apply[points3d]{
 Returns a renderer that draws points in 3D space.
 
-A scatter plot of points sampled uniformly from the surface of a sphere:
+For example, a scatter plot of points sampled uniformly from the surface of a sphere:
 @interaction[#:eval plot-eval
                     (let ()
                       (define (runif) (- (* 2 (random)) 1))
@@ -38,10 +49,11 @@ A scatter plot of points sampled uniformly from the surface of a sphere:
 @section{3D Line Renderers}
 
 @doc-apply[lines3d]{
-
+Returns a renderer that draws connected lines, with points in 3D space.
 }
 
 @doc-apply[parametric3d]{
+Returns a renderer that plots a vector-valued function of time. For example,
 @interaction[#:eval plot-eval
                     (plot3d (parametric3d (λ (t)
                                             (vector (* (cos (* 80 t)) (cos t))
@@ -55,6 +67,7 @@ A scatter plot of points sampled uniformly from the surface of a sphere:
 @section{3D Surface Renderers}
 
 @doc-apply[surface3d]{
+Returns a renderer that plots a two-input, one-output function. For example,
 @interaction[#:eval plot-eval (plot3d (list (surface3d (λ (x y) (+ (sqr x) (sqr y))) -1 1 -1 1
                                                        #:label "z = x^2 + y^2")
                                             (surface3d (λ (x y) (- (+ (sqr x) (sqr y)))) -1 1 -1 1
@@ -63,9 +76,14 @@ A scatter plot of points sampled uniformly from the surface of a sphere:
 }
 
 @doc-apply[polar3d]{
+Returns a renderer that plots a function from latitude and longitude to radius.
 
+Currently, latitudes range from @(racket 0) to @(racket (* 2 pi)), and longitudes from @(racket (* -1/2 pi)) to @(racket (* 1/2 pi)).
+
+A sphere is the graph of a polar function of constant radius:
 @interaction[#:eval plot-eval (plot3d (polar3d (λ (θ ρ) 1)) #:altitude 25)]
 
+Combining polar function renderers allows faking latitudes or longitudes in larger ranges, to get, for example, a seashell plot:
 @interaction[#:eval plot-eval
                     (let ()
                       (define (f1 θ ρ) (+ 1 (/ θ 2 pi) (* 1/8 (sin (* 8 ρ)))))
@@ -81,12 +99,22 @@ A scatter plot of points sampled uniformly from the surface of a sphere:
 @section{3D Contour Renderers}
 
 @doc-apply[contours3d]{
+Returns a renderer that plots contour lines on the surface of a function.
+
+The appearance keyword arguments are interpreted identically to the appearance keyword arguments to @(racket contours).
+In particular, when @(racket levels) is @(racket 'auto), contour values correspond precisely to @italic{z} axis ticks.
+
+For example,
 @interaction[#:eval plot-eval (plot3d (contours3d (λ (x y) (+ (sqr x) (sqr y))) -1.1 1.1 -1.1 1.1
                                                   #:label "z = x^2 + y^2")
                                       #:legend-anchor 'top-left)]
 }
 
 @doc-apply[contour-intervals3d]{
+Returns a renderer that plots contour intervals and contour lines on the surface of a function.
+The appearance keyword arguments are interpreted identically to the appearance keyword arguments to @(racket contour-intervals).
+
+For example,
 @interaction[#:eval plot-eval (plot3d (contour-intervals3d (λ (x y) (+ (sqr x) (sqr y)))
                                                            -1.1 1.1 -1.1 1.1
                                                            #:label "z = x^2 + y^2")
@@ -96,6 +124,9 @@ A scatter plot of points sampled uniformly from the surface of a sphere:
 @section{3D Isosurface Renderers}
 
 @doc-apply[isosurface3d]{
+Returns a renderer that plots the surface of constant output value of the function @(racket f). The argument @(racket d) is the constant value.
+
+For example, a sphere is all the points in which the Euclidean distance function returns the sphere's radius:                                                           
 @interaction[#:eval plot-eval (plot3d (isosurface3d
                                        (λ (x y z) (sqrt (+ (sqr x) (sqr y) (sqr z)))) 1
                                        -1 1 -1 1 -1 1)
@@ -103,6 +134,9 @@ A scatter plot of points sampled uniformly from the surface of a sphere:
 }
 
 @doc-apply[isosurfaces3d]{
+Returns a renderer that plots multiple isosurfaces. The appearance keyword arguments are interpreted similarly to those of @(racket contours).
+
+Use this to visualize functions from three inputs to one output; for example:
 @interaction[#:eval plot-eval (let ()
                                 (define (saddle x y z) (- (sqr x) (* 1/2 (+ (sqr y) (sqr z)))))
                                 (plot3d (isosurfaces3d saddle #:d-min -1 #:d-max 1 #:label "")
@@ -110,13 +144,19 @@ A scatter plot of points sampled uniformly from the surface of a sphere:
                                         #:y-min -2 #:y-max 2
                                         #:z-min -2 #:z-max 2
                                         #:legend-anchor 'top-left))]
+
+If it helps, think of the output of @(racket f) as a density or charge.
 }
 
 @section{3D Rectangle Renderers}
 
 @doc-apply[rectangles3d]{
+Returns a renderer that draws rectangles.
+
+This can be used to draw histograms; for example,
 @interaction[#:eval plot-eval
                     (let ()
+                      (define (norm2 x y) (exp (* -1/2 (+ (sqr (- x 5)) (sqr y)))))
                       (define x-ivls (bounds->intervals (linear-seq 2 8 10)))
                       (define y-ivls (bounds->intervals (linear-seq -5 5 10)))
                       (define x-mids (linear-seq 2 8 9 #:start? #f #:end? #f))
@@ -126,13 +166,16 @@ A scatter plot of points sampled uniformly from the surface of a sphere:
                                                         [y  (in-list y-mids)])
                                                (for/list ([x-ivl  (in-list x-ivls)]
                                                           [x  (in-list x-mids)])
-                                                 (define z (exp (* -1/2 (+ (sqr (- x 5)) (sqr y)))))
+                                                 (define z (norm2 x y))
                                                  (vector x-ivl y-ivl (ivl 0 z)))))
                                             #:alpha 3/4
-                                            #:label "Approximate 2D Normal")))]
+                                            #:label "Appx. 2D Normal")))]
 }
 
 @doc-apply[discrete-histogram3d]{
+Returns a renderer that draws discrete histograms on a two-valued domain.
+
+Missing pairs are not drawn; for example,
 @interaction[#:eval plot-eval
                     (plot3d (discrete-histogram3d '(#(a a 1) #(a b 2) #(b b 3))
                                                   #:label "Missing (b,a)"