limit the extraction to an rectangular region
a pointer to the newly allocated image surface. The caller must use cairo.surface.Surface.unmapImage to destroy this image surface.
This function always returns a valid pointer, but it will return a pointer to a "nil" surface if other is already in an error state or any other error occurs. If the returned pointer does not have an error status, it is guaranteed to be an image surface whose format is not cairo.types.Format.Invalid.
Returns an image surface that is the most efficient mechanism for modifying the backing store of the target surface. The region retrieved may be limited to the extents or null for the whole surface
Note, the use of the original surface as a target or source whilst it is mapped is undefined. The result of mapping the surface multiple times is undefined. Calling cairo.surface.Surface.destroy or cairo.surface.Surface.finish on the resulting image surface results in undefined behavior. Changing the device transform of the image surface or of surface before the image surface is unmapped results in undefined behavior.