Merge pull request #2602 from whydoubt/image-tobytes-pitch

Implement pitch argument for image.tobytes()

Author: Starbuck5

buildconfig/stubs/pygame/image.pyi

@@ -21,6 +21,7 @@ def tostring(
     surface: Surface,
     format: _to_string_format,
     flipped: bool = False,
+    pitch: int = -1,
 ) -> bytes: ...
 def fromstring(
     bytes: bytes,
@@ -32,7 +33,10 @@ def fromstring(
 
 # the use of tobytes/frombytes is preferred over tostring/fromstring
 def tobytes(
-    surface: Surface, format: _to_string_format, flipped: bool = False
+    surface: Surface,
+    format: _to_string_format,
+    flipped: bool = False,
+    pitch: int = -1,
 ) -> bytes: ...
 def frombytes(
     bytes: bytes,

docs/reST/ref/image.rst

@@ -195,7 +195,7 @@ following formats.
 .. function:: tostring
 
    | :sl:`transfer image to byte buffer`
-   | :sg:`tostring(Surface, format, flipped=False) -> bytes`
+   | :sg:`tostring(Surface, format, flipped=False, pitch=-1) -> bytes`
 
    DEPRECATED: This function has the same functionality as :func:`tobytes()`, which is preferred and should be used.
 
@@ -206,7 +206,7 @@ following formats.
 .. function:: tobytes
 
    | :sl:`transfer image to byte buffer`
-   | :sg:`tobytes(Surface, format, flipped=False) -> bytes`
+   | :sg:`tobytes(Surface, format, flipped=False, pitch=-1) -> bytes`
 
    Creates a string of bytes that can be transferred with the ``fromstring``
    or ``frombytes`` methods in other Python imaging packages. Some Python
@@ -235,12 +235,19 @@ following formats.
 
       * ``ARGB_PREMULT``, 32-bit image with colors scaled by alpha channel, alpha channel first
 
+   The 'pitch' argument can be used to specify the pitch/stride per horizontal line
+   of the image in bytes. It must be equal to or greater than how many bytes
+   the pixel data of each horizontal line in the image bytes occupies without any
+   extra padding. By default, it is ``-1``, which means that the pitch/stride is
+   the same size as how many bytes the pure pixel data of each horizontal line takes.
+
    .. note:: The use of this function is recommended over :func:`tostring` as of pygame 2.1.3.
              This function was introduced so it matches nicely with other 
              libraries (PIL, numpy, etc), and with people's expectations.
 
    .. versionadded:: 2.1.3 
    .. versionchanged:: 2.2.0 Now supports keyword arguments.
+   .. versionchanged:: 2.5.0 Added a 'pitch' argument.
 
    .. ## pygame.image.tobytes ##
 

src_c/doc/image_doc.h

@@ -5,8 +5,8 @@
 #define DOC_IMAGE_SAVE "save(Surface, file) -> None\nsave(Surface, file, namehint="") -> None\nsave an image to file (or file-like object)"
 #define DOC_IMAGE_GETSDLIMAGEVERSION "get_sdl_image_version(linked=True) -> None\nget_sdl_image_version(linked=True) -> (major, minor, patch)\nget version number of the SDL_Image library being used"
 #define DOC_IMAGE_GETEXTENDED "get_extended() -> bool\ntest if extended image formats can be loaded"
-#define DOC_IMAGE_TOSTRING "tostring(Surface, format, flipped=False) -> bytes\ntransfer image to byte buffer"
-#define DOC_IMAGE_TOBYTES "tobytes(Surface, format, flipped=False) -> bytes\ntransfer image to byte buffer"
+#define DOC_IMAGE_TOSTRING "tostring(Surface, format, flipped=False, pitch=-1) -> bytes\ntransfer image to byte buffer"
+#define DOC_IMAGE_TOBYTES "tobytes(Surface, format, flipped=False, pitch=-1) -> bytes\ntransfer image to byte buffer"
 #define DOC_IMAGE_FROMSTRING "fromstring(bytes, size, format, flipped=False, pitch=-1) -> Surface\ncreate new Surface from a byte buffer"
 #define DOC_IMAGE_FROMBYTES "frombytes(bytes, size, format, flipped=False, pitch=-1) -> Surface\ncreate new Surface from a byte buffer"
 #define DOC_IMAGE_FROMBUFFER "frombuffer(buffer, size, format, pitch=-1) -> Surface\ncreate a new Surface that shares data inside a bytes buffer"