CGContextSaveGStatecontext

CGContextSaveGState is a Core Graphics function that preserves the current state of a graphics context. The function takes one argument, a CGContextRef named context, and stores a snapshot of the context’s attributes in a stack. The saved state includes transformation matrices, clipping paths, alpha values, fill and stroke colors, line width, and other drawing parameters. When the function is invoked, the graphics context pushes the current state onto an internal stack, allowing subsequent drawing operations to modify the context without permanently altering the original configuration.

The paired function CGContextRestoreGState retrieves the previously saved state by popping the top entry from the stack and restoring the context to that point. If no state is present on the stack, the restore function has no effect. Because the stack operations are LIFO, multiple calls to save and restore can be nested to maintain complex drawing states.

Usage of CGContextSaveGState is common in graphic rendering pipelines where temporary changes to the graphics context are required, such as rotating a piece of text or changing the line width for a single stroke. By saving the state before the change and restoring it afterward, developers ensure that subsequent drawing operations remain unaffected.

The function is declared in the Core Graphics framework header CGContext.h and is available on macOS, iOS, tvOS, and watchOS. Documentation indicates that the function has a void return type and may be called on any valid CGContextRef. The function is thread safe for contexts that are not shared between threads.

Relevant functions include CGContextSetStrokeColorWithColor, CGContextConcatCTM, and CGContextClipToRect, all of which modify the graphics context state that CGContextSaveGState can preserve. This allows developers to maintain clean and predictable rendering pipelines, especially in complex drawing scenarios.