Meaning of offset in pygame Mask.overlap methods

Question

I have a situation in which two rectangles collide, and I have to detect how much did they collide so I can redraw the objects in a way that they are only touching each other's edges.

It's a situation in which a moving ball should hit a completely unmovable wall and instantly stop moving. Since the ball sometimes moves multiple pixels per screen refresh, it is possible that it enters the wall with more than half its surface when the collision is detected, in which case I want to shift its position back to the point where it only touches the edges of the wall.

Here is the conceptual image it:

I decided to implement this with masks, and thought that I could supply the masks of both objects (wall and ball) and get the surface (as a square) of their intersection. However, there is also the offset parameter which I don't understand.

Here are the docs for the method:

Mask.overlap

    Returns the point of intersection if the masks 
    overlap with the given offset - or None if it does not overlap.
    Mask.overlap(othermask, offset) -> x,y

    The overlap tests uses the following offsets (which may be negative):

   +----+----------..
   |A   | yoffset
   |  +-+----------..
   +--|B
   |xoffset
   |  |
   :  :

Answer 1

The offset gets added to the coordinates of all parts of the mask that you pass into the function.

So, if you have mask A:

000
001
001

and mask B:

000
010
000

and you ask

A.overlap(B, (ofsx, ofsy))

then ofsx and ofsy are added to the coordinates of B.

Imagine both masks in the context of a large raster with the top-left corner of A at the origin. B is shifted (ofsx, ofsy) within that raster before its overlap with A is calculated.

For example if you ask

A.overlap(B, (3, 4))

Then the following raster is evaluated for overlaps:

X X X X X X X X X X X X X X X X
X X X X X X X X X X X X X X X X
X X X X X X X X X X X X X X X X
X X X X X X X X X X X X X X X X
X X X X X X X X X X X X X X X X
X X X X X X X|0 0 0|X X X X X X
X X X X X X X|0 0 1|X X X X X X
X X X X X X X|0 0 1|X X X X X X
X X X X X X X X X X X X X X X X
X X X X X X X X X X|0 0 0|X X X <-  B @ imaginary origin + (3, 4)
X X X X X X X X X X|0 1 0|X X X
X X X X X X X X X X|0 0 0|X X X
X X X X X X X X X X X X X X X X
             ^     
             |     
             A @ imaginary origin

if you put negative values into the offset parameter, it shifts B in the other direction.