CGContextRestoreGState

CGContextRestoreGState is a Core Graphics function that restores the graphics state of a given drawing context from a stack of saved states. It replaces the current graphics state with the most recently saved state and pops that saved copy off the stack.

The function is designed to be paired with CGContextSaveGState. A common pattern is to save the current state before making local changes (such as transforming the coordinate system, clipping region, colors, line width, dash patterns, font, or text matrix), perform drawing, and then call CGContextRestoreGState to return to the previous state. By restoring, any changes made after the save—including clipping paths, transforms, and drawing attributes—are discarded and the prior state is restored exactly as it was.

Attributes that are part of the graphics state and thus restored include the current transform (CTM), clipping region, stroke and fill colors, line width and style, dash pattern, text matrix and font settings, and other drawing parameters. The clipping region and transform, for example, are reset to their saved values when the state is restored.

Notes and limitations: the function operates on a per-context graphics state stack and must be balanced with a prior save; calling restore without a corresponding save or in an invalid state can lead to undefined behavior. CGContextRestoreGState is available on macOS and iOS, and is commonly used in drawing code to manage complex or nested drawing operations in a clean, reusable way.