pam: add PAM_PITCH_CONTINUOUS placeholder for pitch

If the value of pitch is "default", it ti actually a bit tricky to set
the value explicitly.

Also the value was set incorrectly in HEAD^^ - pitch equals width only
for single channel + 8-bit.

added doxy

Author: MartinPulec

src/utils/pam.c

@@ -275,7 +275,7 @@ bool pam_write(const char *filename, unsigned int width, unsigned int pitch,
         const size_t len = width * linesize;
         errno = 0;
         size_t bytes_written = 0;
-        if (width == pitch) {
+        if (pitch == PAM_PITCH_CONTINUOUS || width == pitch) {
                 bytes_written = fwrite((const char *) data, 1, len, file);
         } else {
                 for (unsigned y = 0; y < height; ++y) {

src/utils/pam.h

@@ -49,16 +49,50 @@
 extern "C" {
 #endif
 
+/// metadata read from file
 struct pam_metadata {
-        int width;
-        int height;
-        int ch_count;
-        int maxval;
-        bool bitmap_pbm; // bitmap data is stored in PBM format (1 bit per pixel, line aligned to whole byte, 1 is black /"ink on"/),
-                         // otherwise 1 byte per pixel, 1 is white "light on"); if .depth != 1 || .maxval != 1, this value is undefined
+        int width;    ///< image width
+        int height;   ///< image height
+        int ch_count; ///< number of channels
+        int maxval;   ///< sample maximal value (typically but not necessarily
+                      ///< 255)
+        bool bitmap_pbm; ///< bitmap data is stored in PBM format (1 bit per
+                         ///< pixel, line aligned to whole byte, 1 is black
+                         ///< /"ink on"/), otherwise 1 byte per pixel, 1 is
+                         ///< white "light on"); if .depth != 1 || .maxval != 1,
+                         ///< this value is undefined
 };
 
+/**
+ * read PAM/PNM file
+ *
+ * @param      filename   file name
+ * @param[out] info       pointer to metadata struct
+ * @param[out] data       pointer to byte array, can be 0, in which case no data
+ *                        are written (only metadata read )
+ * @param[out] allocaltor allocator to alloc @ref data; if 0, no data are
+ *                        read/allocated, only @ref info set
+ */
 bool pam_read(const char *filename, struct pam_metadata *info, unsigned char **data, void *(*allocator)(size_t));
+
+enum {
+        PAM_PITCH_CONTINUOUS = 0,
+};
+
+/**
+ * write PAM or PNM file
+ *
+ * @param filename file name to be written to
+ * @param width    image width
+ * @param pitch    input line pitch in bytes; PAM_PITCH_CONTINUOUS can be used
+ *                 if input pitch == width * ch_count * (maxval <= 255 ? 1 : 2)
+ * @param height   image height
+ * @param ch_count image channel count (1-4 for output PAM, 1 or 3 for PNM, see
+ *                 @ref pnm)
+ * @param maxval   maximal sample value, typically 255 for 8-bit
+ * @param data     bytes to be written
+ * @param pnm      use PNM file (instead of PAM)
+ */
 bool pam_write(const char *filename, unsigned int width, unsigned int pitch,
                unsigned int height, int ch_count, int maxval,
                const unsigned char *data, bool pnm);

src/video_frame.c

@@ -481,7 +481,7 @@ bool save_video_frame_as_pnm(struct video_frame *frame, const char *name)
                 return false;
         }
 
-        pam_write(name, tile->width, tile->width, tile->height, 3,
+        pam_write(name, tile->width, PAM_PITCH_CONTINUOUS, tile->height, 3,
                   (1 << get_bits_per_component(frame->color_spec)) - 1, data,
                   true);
         free(tmp_data);