Ticket #2458: tex_comments.patch

source/lib/tex/tex.cpp

@@ -462 +462 @@
 
 TIMER_ADD_CLIENT(tc_transform);
 
-// change <t>'s pixel format by flipping the state of all TEX_* flags
+// change the pixel format by flipping the state of all TEX_* flags
 // that are set in transforms.
 Status Tex::transform(size_t transforms)
 {
@@ -489 +489 @@
 }
 
 
-// change <t>'s pixel format to the new format specified by <new_flags>.
-// (note: this is equivalent to tex_transform(t, t->flags^new_flags).
+// change the pixel format to the new format specified by <new_flags>.
+// (note: this is equivalent to transform(t, t->flags^new_flags).
 Status Tex::transform_to(size_t new_flags)
 {
-    // tex_transform takes care of validating <t>
+    // transform takes care of validating
     const size_t transforms = m_Flags ^ new_flags;
     return transform(transforms);
 }
@@ -559 +559 @@
 //-----------------------------------------------------------------------------
 
 // indicate if <filename>'s extension is that of a texture format
-// supported by tex_load. case-insensitive.
+// supported by Tex::load. case-insensitive.
 //
-// rationale: tex_load complains if the given file is of an
+// rationale: Tex::load complains if the given file is of an
 // unsupported type. this API allows users to preempt that warning
 // (by checking the filename themselves), and also provides for e.g.
 // enumerating only images in a file picker.
@@ -580 +580 @@
 
 
 // store the given image data into a Tex object; this will be as if
-// it had been loaded via tex_load.
+// it had been loaded via Tex::load.
 //
 // rationale: support for in-memory images is necessary for
 //   emulation of glCompressedTexImage2D and useful overall.
@@ -609 +609 @@
 // use of it impossible.
 void Tex::free()
 {
-    // do not validate <t> - this is called from tex_load if loading
+    // do not validate - this is called from Tex::load if loading
     // failed, so not all fields may be valid.
 
     m_Data.reset();
@@ -756 +756 @@
 
     // we could be clever here and avoid the extra alloc if our current
     // memory block ensued from the same kind of texture file. this is
-    // most likely the case if in_img == tex_get_data() + c->hdr_size(0).
+    // most likely the case if in_img == get_data() + c->hdr_size(0).
     // this would make for zero-copy IO.
 
     const size_t max_out_size = img_size()*4 + 256*KiB;

source/lib/tex/tex.h

@@ -304 +304 @@
     //
 
     /**
-     * Change \<t\>'s pixel format.
+     * Change the pixel format.
      *
      * @param transforms TexFlags that are to be flipped.
      * @return Status
@@ -312 +312 @@
     Status transform(size_t transforms);
 
     /**
-     * Change \<t\>'s pixel format (2nd version)
-     * (note: this is equivalent to tex_transform(t, t-\>flags^new_flags).
+     * Change the pixel format (2nd version)
+     * (note: this is equivalent to Tex::transform(t, t-\>flags^new_flags).
      *
      * @param new_flags desired new value of TexFlags.
      * @return Status
@@ -325 +325 @@
     //
 
     /**
-     * rationale: since Tex is a struct, its fields are accessible to callers.
-     * this is more for C compatibility than convenience; the following should
-     * be used instead of direct access to the corresponding fields because
-     * they take care of some dirty work.
-     **/
-
-    /**
      * return a pointer to the image data (pixels), taking into account any
      * header(s) that may come before it.
      *

source/lib/tex/tex_codec.h

@@ -56 +56 @@
      * encode the texture data into the codec's file format (in memory).
      *
      * @param t input texture object. note: non-const because encoding may
-     * require a tex_transform.
+     * require a Tex::transform.
      * @param da output data array, allocated by codec.
      * rationale: some codecs cannot calculate the output size beforehand
      * (e.g. PNG output via libpng), so the output memory cannot be allocated