FLTK logo

[master] cc0657d - Improve documentation of Fl_Image (Issue #272)

FLTK matrix user chat room
(using Element browser app)   FLTK gitter user chat room   GitHub FLTK Project   FLTK News RSS Feed  
  FLTK Apps      FLTK Library      Forums      Links     Login 
 All Forums  |  Back to fltk.commit  ]
 
Previous Message ]Next Message ]

[master] cc0657d - Improve documentation of Fl_Image (Issue #272) "Albrecht Schlosser" Sep 09, 2021  
 
commit cc0657d7a7872ae587dee5dd16472d793eadca7c
Author:     Albrecht Schlosser <albrechts.fltk@online.de>
AuthorDate: Thu Sep 9 17:53:00 2021 +0200
Commit:     Albrecht Schlosser <albrechts.fltk@online.de>
CommitDate: Thu Sep 9 17:53:54 2021 +0200

    Improve documentation of Fl_Image (Issue #272)
    
    Try to explain what count() returns and what data() contains which
    can be different by image type.

 FL/Fl_Image.H | 43 ++++++++++++++++++++++++++++++++++---------
 1 file changed, 34 insertions(+), 9 deletions(-)

diff --git FL/Fl_Image.H FL/Fl_Image.H
index f39e0ea..4a2025a 100644
--- FL/Fl_Image.H
+++ FL/Fl_Image.H
@@ -108,8 +108,12 @@ protected:
    */
   void ld(int LD) {ld_ = LD;}
   /**
-   Sets the current array pointer and count of pointers in the array.
-   */
+    Sets the current data pointer and count of pointers in the array.
+
+    There can be 0, 1, or more pointers to actual image data in an image.
+
+   \see const char* const* data(), count(), w(), h(), data_w(), data_h(), d(), ld()
+  */
   void data(const char * const *p, int c) {data_ = p; count_ = c;}
   void draw_empty(int X, int Y);
 
@@ -151,15 +155,36 @@ public:
    */
   int ld() const {return ld_;}
   /**
-   The count() method returns the number of data values
-   associated with the image. The value will be 0 for images with
-   no associated data, 1 for bitmap and color images, and greater
-   than 2 for pixmap images.
-   */
+    Returns the number of data values associated with the image.
+
+    The value will be 0 for images with no associated data, 1 for
+    bitmap and color images, and greater than 2 for pixmap images.
+
+    \see data()
+  */
   int count() const {return count_;}
   /**
-   Returns a pointer to the current image data array.
-   Use the count() method to find the size of the data array.
+    Returns a pointer to the current image data array.
+
+    There can be 0, 1, or more pointers to actual image data in an image.
+
+    Use the count() method to find the size of the data array. You must
+    not dereference the data() pointer if count() equals zero.
+
+    \note data() \b may return NULL.
+
+    Example:
+
+    Fl_RGB_Image has exactly one pointer which points at the R, G, B [, A]
+    data array of the image. The total size of this array depends on
+    several attributes like w(), h(), data_w(), data_h(), d() and ld()
+    and is basically data_w() * data_h() * d() but there are exceptions
+    if ld() is non-zero: see description of ld().
+
+    Other image types have different numbers and types of data pointers
+    which are implementation details and not documented here.
+
+    \see count(), w(), h(), data_w(), data_h(), d(), ld()
    */
   const char * const *data() const {return data_;}
   int fail();
Direct Link to Message ]
 
     
Previous Message ]Next Message ]
 
 

Comments are owned by the poster. All other content is copyright 1998-2024 by Bill Spitzak and others. This project is hosted by The FLTK Team. Please report site problems to 'erco@seriss.com'.