cairo:surface-create-for-rectangle (target x y width height)

target -- an existing cairo:surface-t instance for which the subsurface will point to
x -- a number coerced to a double float for the x origin of the subsurface from the top-left of the target surface, in device-space units
y -- a number coerced to a double float for the y origin of the subsurface from the top-left of the target surface, in device-space units
width -- a number coerced to a double float for the width of the subsurface, in device-space units
height -- a number coerced to a double float for the height of the subsurface, in device-space units

The newly allocated cairo:surface-t instance. The caller owns the surface and should call the cairo:surface-destroy function when done with it. This function always returns a valid surface, but it will return "nil" surface if target is already in an error state or any other error occurs.

Create a new surface that is a rectangle within the target surface. All operations drawn to this surface are then clipped and translated onto the target surface. Nothing drawn via this subsurface outside of its bounds is drawn onto the target surface, making this a useful method for passing constrained child surfaces to library routines that draw directly onto the parent surface, that is with no further backend allocations, double buffering or copies. The semantics of subsurfaces have not been finalized yet unless the rectangle is in full device units, is contained within the extents of the target surface, and the target or device of the subsurface transforms are not changed.