CGGradient: o que é, tipos de gradientes e sua criação

O que é CGGradient?

CGGradient é um objeto imutável no Core Graphics que encapsula um conjunto de cores e regras para misturá-las ao longo de uma transição gradiente. Internamente, o CGGradient armazena uma matriz de CGColor, uma matriz de posições (locations) no intervalo [0.0, 1.0] e uma referência ao CGColorSpace no qual as cores são interpretadas. Cada cor está associada a uma posição na escala do gradiente: a posição 0.0 corresponde ao início, 1.0 ao final da transição.

Ao criar um CGGradient através da função CGGradientCreateWithColors, o Core Graphics pré-calcula os valores de cor intermediários. Um gradiente pode conter um número arbitrário de paradas de cor (color stops), permitindo transições complexas de múltiplas cores. O número de cores deve ser de pelo menos duas, e cada cor deve corresponder a uma posição na matriz de locations.

A arquitetura do CGGradient difere de APIs de nível superior, como CAGradientLayer do Core Animation, por trabalhar diretamente no contexto do Core Graphics. Isso proporciona controle total sobre o processo de desenho e a capacidade de combinar gradientes com outras operações do Quartz 2D — máscaras de recorte, sombras e transformações.

Gradientes lineares e radiais

Core Graphics suporta dois tipos de gradientes: linear (axial) e radial. Um gradiente linear é criado com a função CGGradientCreateWithColors e desenhado com CGContextDrawLinearGradient. Um gradiente radial requer a mesma estrutura CGGradient, mas é desenhado com CGContextDrawRadialGradient.

Gradiente linear (Axial)

Gradiente linear estende a transição de cor ao longo de uma linha reta do ponto inicial startPoint ao ponto final endPoint. As cores são interpoladas entre esses dois pontos, e o comportamento além deles é controlado pelas opções de extensão. O gradiente linear é ideal para criar fundos suaves, simular superfícies metálicas e transições de cor em elementos de interface.

Gradiente radial

Gradiente radial cria uma transição de cor de um círculo para outro. Cada círculo é definido por um centro (startCenter / endCenter) e um raio (startRadius / endRadius). A cor é interpolada do círculo interno para o externo. Um caso especial é quando o raio inicial é 0: o gradiente irradia de um único ponto. Os gradientes radiais são usados para simular fontes de luz, lentes, corpos celestes e efeitos de foco.

Criar CGGradient: cores e posições

CGGradient é criado com apenas uma função base — CGGradientCreateWithColors. A função recebe um CGColorSpace, uma matriz de CGColor (CFArray) e uma matriz de CGFloat locations. Se locations for NULL, as cores são distribuídas uniformemente ao longo da escala do gradiente. Se locations forem especificadas, sua quantidade deve corresponder ao número de cores.

A matriz locations contém valores de 0.0 a 1.0 que definem os pontos de parada para cada cor. Os valores devem aumentar monotonicamente. Se o primeiro valor for maior que 0.0, a cor do início até esta posição é extrapolada da cor na posição 0.0. Da mesma forma para o último valor menor que 1.0. Este comportamento é controlado pelas opções de extensão durante o desenho.

Ao escolher cores para um gradiente, é importante considerar o espaço de cor. Todas as cores em um único CGGradient devem pertencer ao mesmo CGColorSpace — o Core Graphics interpola os componentes nesse espaço. Se as cores forem criadas em espaços diferentes, elas devem primeiro ser convertidas para um espaço comum usando CGColorCreateCopyByMatchingToColorSpace.

Desenhar um gradiente no contexto

Core Graphics fornece duas funções para desenhar um gradiente: CGContextDrawLinearGradient para linear e CGContextDrawRadialGradient para radial. Ambas as funções aceitam um contexto gráfico, um objeto CGGradient, opções de extensão e parâmetros geométricos específicos do tipo. O desenho é realizado levando em conta a máscara de recorte atual e a transformação do contexto.

Opções de extensão (Gradient Options)

Opções de extensão controlam o comportamento do gradiente além do intervalo de posições 0.0–1.0. A constante kCGGradientDrawsBeforeStartLocation preenche a área antes da posição inicial com a cor da primeira parada. kCGGradientDrawsAfterEndLocation preenche com a cor da última parada. Essas opções podem ser combinadas através de uma máscara de bits. Para gradientes radiais, as opções se aplicam à área além dos raios inicial e final.

Efeito das transformações

O gradiente é desenhado no sistema de coordenadas do contexto gráfico atual, levando em conta sua transformação (CTM — Current Transformation Matrix). Aplicar CGContextTranslateCTM, CGContextScaleCTM ou CGContextRotateCTM antes de chamar a função de desenho altera a posição e a escala do gradiente. Isso permite reutilizar um único CGGradient para diferentes áreas sem criar novos objetos.

Opções: extensão, suavização e mascaramento

Core Graphics fornece vários mecanismos adicionais para controlar gradientes: suavização (antialiasing), mascaramento através de máscara de recorte (clipping mask) e combinação com efeitos de transparência. A suavização está ativada por padrão no contexto gráfico e é controlada via CGContextSetShouldAntialias.

Máscara de recorte permite restringir a área de desenho do gradiente a uma forma arbitrária. Antes de chamar CGContextDrawLinearGradient, é necessário definir um caminho através de CGContextBeginPath, CGContextAddPath e CGContextClip. O gradiente é desenhado apenas dentro da área delimitada por este caminho. Isso é amplamente usado para criar ícones gradientes, botões e barras de progresso.

Extensão do gradiente é outro parâmetro importante. Ao usar kCGGradientDrawsBeforeStartLocation, o Core Graphics extrapola a cor da primeira parada por toda a área antes de startPoint. Sem esta opção, a área fora do gradiente permanece não preenchida (transparente). A combinação de ambas as opções garante que todo o retângulo do contexto gráfico seja preenchido com um gradiente, mesmo se startPoint e endPoint estiverem dentro dele.

Exemplos de código Swift

Vejamos exemplos práticos de criação e desenho de gradientes no iOS usando CGGradient e Core Graphics.

Gradiente linear com três cores

Este exemplo cria um gradiente linear com três cores (azul, verde, vermelho) e o desenha diagonalmente através de uma UIView. A matriz locations distribui as cores de forma desigual: azul de 0.0 a 0.3, verde em 0.6, vermelho de 0.6 a 1.0.

func drawLinearGradient(in ctx: CGContext,
                          rect: CGRect) {
    let colors = [
        UIColor.blue.cgColor,
        UIColor.green.cgColor,
        UIColor.red.cgColor
    ] as CFArray

    let locations: [CGFloat] = [0.0, 0.6, 1.0]
    let space = CGColorSpaceCreateDeviceRGB()

    guard let gradient = CGGradientCreateWithColors(
        space, colors, locations
    ) else { return }

    let start = CGPoint(x: 0, y: 0)
    let end = CGPoint(x: rect.width,
                         y: rect.height)

    ctx.drawLinearGradient(gradient,
        start: start, end: end,
        options: [.drawsBeforeStartLocation,
                  .drawsAfterEndLocation])
}

Gradiente radial com efeito de brilho

Este exemplo desenha um gradiente radial simulando um efeito de brilho. O ponto inicial com raio zero define o centro do brilho, e o círculo externo define o limite de atenuação. Este efeito é usado para destacar elementos da interface ou indicadores de atividade.

func drawRadialGlow(in ctx: CGContext,
                     center: CGPoint) {
    let colors = [
        UIColor.white.cgColor,
        UIColor.orange.cgColor,
        UIColor.clear.cgColor
    ] as CFArray
    let locations: [CGFloat] = [0.0, 0.4, 1.0]

    let gradient = CGGradientCreateWithColors(
        CGColorSpaceCreateDeviceRGB(), colors, locations)

    ctx.drawRadialGradient(gradient,
        startCenter: center, startRadius: 0,
        endCenter: center, endRadius: 100,
        options: [.drawsBeforeStartLocation,
                  .drawsAfterEndLocation])
}

Gradiente com máscara de recorte

Neste exemplo, o gradiente é restrito a uma área circular através de um caminho de recorte. Antes de desenhar o gradiente, um caminho circular é definido, que se torna a máscara atual do contexto. O gradiente preenche apenas a área dentro do círculo, criando um efeito de ícone gradiente.

func drawGradientInCircle(in ctx: CGContext,
                          rect: CGRect) {
    // Creating circular clip path
    let circlePath = CGMutablePath()
    circlePath.addEllipse(in: rect)
    ctx.addPath(circlePath)
    ctx.clip()

    // Drawing gradient inside clip mask
    let colors = [UIColor.magenta.cgColor,
                    UIColor.cyan.cgColor]
    let gradient = CGGradientCreateWithColors(
        CGColorSpaceCreateDeviceRGB(),
        colors as CFArray, nil)

    ctx.drawLinearGradient(gradient,
        start: CGPoint(x: 0, y: 0),
        end: CGPoint(x: rect.width,
                     y: rect.height),
        options: [.drawsBeforeStartLocation])
}