Amendment: get rid of z parameter to write_scanline

Signed-off-by: Larry Gritz <lg@larrygritz.com>

Author: lgritz

src/include/OpenImageIO/imageio.h

@@ -2321,16 +2321,16 @@ class OIIO_API ImageOutput {
         return write_image(ispan);
     }
 
-    /// Write one scanline that include pixels (*,y,z) from `data`, which is
-    /// an `image_span` of un-typed bytes incorporating its bounded dimensions
+    /// Write one scanline that include pixels (*,y) from `data`, which is an
+    /// `image_span` of un-typed bytes incorporating its bounded dimensions
     /// and strides. The data type is given explicity by the `format`
     /// argument, and will be automatically converted to the type being stored
     /// in the file.
     ///
     /// The image_span must have a width equal to a full scanline width,
     /// and its height and depth must be 1.
     ///
-    /// @param  y/z         The y & z coordinates of the scanline.
+    /// @param  y           The y coordinate of the scanline.
     /// @param  format      A TypeDesc describing the type of the pixel data
     ///                     that `data`'s memory contains. Use `TypeUnknown`
     ///                     to indicate that the data is already in the native
@@ -2340,34 +2340,32 @@ class OIIO_API ImageOutput {
     ///                     dimension (channel, x, y, z).
     /// @returns            `true` upon success, or `false` upon failure.
     ///
-    virtual bool write_scanline(int y, int z, TypeDesc format,
+    virtual bool write_scanline(int y, TypeDesc format,
                                 const image_span<const std::byte>& data);
 
     /// A version of `write_scanline()` taking an `image_span<T>`, where the
     /// type of the underlying data is `T`.  This is a convenience wrapper
     /// around the `write_scanline()` that takes an `image_span<const
     /// std::byte>`.
-    template<typename T>
-    bool write_scanline(int y, int z, const image_span<T>& data)
+    template<typename T> bool write_scanline(int y, const image_span<T>& data)
     {
         // reduce to type + image_span<byte>
-        return write_scanline(y, z, TypeDescFromC<T>::value(),
+        return write_scanline(y, TypeDescFromC<T>::value(),
                               as_image_span_bytes(data));
     }
 
     /// A version of `write_scanline()` taking a `cspan<T>`, which assumes
     /// contiguous strides in all dimensions. This is a convenience wrapper
     /// around the `write_scanline()` that takes an `image_span<const T>`.
-    template<typename T> bool write_scanline(int y, int z, span<T> data)
+    template<typename T> bool write_scanline(int y, span<T> data)
     {
         // reduce to type + image_span<byte>
         auto isize = m_spec.image_bytes(TypeDescFromC<T>::value());
-        return write_scanline(y, z,
-                              image_span<T>(data.data(), m_spec.nchannels,
-                                            m_spec.width, 1, 1));
+        return write_scanline(y, image_span<T>(data.data(), m_spec.nchannels,
+                                               m_spec.width, 1, 1));
     }
 
-    /// Write multiple scanlines that include pixels (*,y,z) for all `ybegin
+    /// Write multiple scanlines that include pixels (*,y) for all `ybegin
     /// <= y < yend`, from `data`, which is an `image_span` of un-typed bytes
     /// incorporating its bounded dimensions and strides. The data type is
     /// given explicity by the `format` argument, and will be automatically
@@ -2380,7 +2378,6 @@ class OIIO_API ImageOutput {
     /// and its height must be yend - ybegin.
     ///
     /// @param  ybegin/yend The y range of the scanlines being passed.
-    /// @param  z           The z coordinate of the scanline.
     /// @param  format      A TypeDesc describing the type of the pixel data
     ///                     that `data`'s memory contains. Use `TypeUnknown`
     ///                     to indicate that the data is already in the native
@@ -2390,32 +2387,32 @@ class OIIO_API ImageOutput {
     ///                     dimension (channel, x, y, z).
     /// @returns            `true` upon success, or `false` upon failure.
     ///
-    virtual bool write_scanlines(int ybegin, int yend, int z, TypeDesc format,
+    virtual bool write_scanlines(int ybegin, int yend, TypeDesc format,
                                  const image_span<const std::byte>& data);
 
     /// A version of `write_scanlines()` taking an `image_span<T>`, where the
     /// type of the underlying data is `T`.  This is a convenience wrapper
     /// around the `write_scanlines()` that takes an `image_span<const
     /// std::byte>`.
     template<typename T>
-    bool write_scanlines(int ybegin, int yend, int z, const image_span<T>& data)
+    bool write_scanlines(int ybegin, int yend, const image_span<T>& data)
     {
         // image_span<T>: reduces to type + byte_buffer
-        return write_scanlines(ybegin, yend, z, TypeDescFromC<T>::value(),
+        return write_scanlines(ybegin, yend, TypeDescFromC<T>::value(),
                                data.as_image_span_bytes());
     }
 
     /// A version of `write_scanlines()` taking a `cspan<T>`, which assumes
     /// contiguous strides in all dimensions. This is a convenience wrapper
     /// around the `write_scanlines()` that takes an `image_span<const T>`.
     template<typename T>
-    bool write_scanlines(int ybegin, int yend, int z, span<T> data)
+    bool write_scanlines(int ybegin, int yend, span<T> data)
     {
         auto ispan = image_span<T>(data.data(), m_spec.nchannels, m_spec.width,
                                    yend - ybegin, 1);
         OIIO_DASSERT(data.size_bytes() == ispan.size_bytes()
                      && ispan.is_contiguous());
-        return write_scanlines(ybegin, yend, z, ispan);
+        return write_scanlines(ybegin, yend, ispan);
     }
 
 

src/libOpenImageIO/imageoutput.cpp

@@ -111,7 +111,7 @@ ImageOutput::write_scanline(int /*y*/, int /*z*/, TypeDesc /*format*/,
 
 
 bool
-ImageOutput::write_scanline(int y, int z, TypeDesc format,
+ImageOutput::write_scanline(int y, TypeDesc format,
                             const image_span<const std::byte>& data)
 {
     size_t sz = (format == TypeUnknown ? m_spec.pixel_bytes(true /*native*/)
@@ -125,7 +125,7 @@ ImageOutput::write_scanline(int y, int z, TypeDesc format,
     }
 
     // Default implementation (for now): call the old pointer+stride
-    return write_scanline(y, z, format, data.data(), data.xstride());
+    return write_scanline(y, 0, format, data.data(), data.xstride());
 }
 
 
@@ -153,7 +153,7 @@ ImageOutput::write_scanlines(int ybegin, int yend, int z, TypeDesc format,
 
 
 bool
-ImageOutput::write_scanlines(int ybegin, int yend, int z, TypeDesc format,
+ImageOutput::write_scanlines(int ybegin, int yend, TypeDesc format,
                              const image_span<const std::byte>& data)
 {
     size_t sz = (format == TypeUnknown ? m_spec.pixel_bytes(true /*native*/)
@@ -167,7 +167,7 @@ ImageOutput::write_scanlines(int ybegin, int yend, int z, TypeDesc format,
     }
 
     // Default implementation (for now): call the old pointer+stride
-    return write_scanlines(ybegin, yend, z, format, data.data(), data.xstride(),
+    return write_scanlines(ybegin, yend, 0, format, data.data(), data.xstride(),
                            data.ystride());
 }
 

testsuite/docs-examples-cpp/src/docs-examples-imageoutput.cpp

@@ -70,10 +70,9 @@ scanlines_write()
     // BEGIN-imageoutput-scanlines
     std::vector<unsigned char> scanline(xres * channels);
     out->open(filename, spec);
-    int z = 0;  // Always zero for 2D images
     for (int y = 0; y < yres; ++y) {
         // ... generate data in scanline[0..xres*channels-1] ...
-        out->write_scanline(y, z, make_span(scanline));
+        out->write_scanline(y, make_span(scanline));
     }
     out->close();
     // END-imageoutput-scanlines