Visão Geral

Um NCLua tem a possibilidade de fazer operações gráficas durante a apresentação de uma aplicação, tais como desenho de linhas, círculos, imagens, etc.

Quando um NCLua é iniciado, automaticamente é instanciado um objeto gráfico que é atribuido à variável global canvas. Este objeto aponta para a região associada ao nó de mídia NCLua no documento NCL e é através dele que todas as operações gráficas são feitas.

Caso o nó de mídia NCLua não esteja associado a nenhuma região, então o valor de canvas será igual a nil.

Se a região associada for, por exemplo:

<region id="luaRegion" width="300" height="100" top="200" left="20"/>

a variável canvas do NCLua correspondente estará associada à região luaRegion de tamanho 300x100 e localizada na posição (20,200).

Além das primitivas gráficas já mencionadas, também é possível instanciar novos canvas, através de um construtor canvas:new(...), e assim representar outros objetos gráficos (layers) que podem, então, ser compostos.

Um objeto canvas guarda em seu estado atributos sob os quais as primitivas gráficas operam, por exemplo, se seu atributo de cor for azul, uma chamada a canvas:drawLine(...) desenhará uma linha azul no canvas. Os atributos são acessados através dos métodos de prefixo attr e sufixo do nome do atributo (e.g. attrColor) que servem tanto para leitura como para escrita (getter e setter).

Repare que o primeiro parâmetro de todos os métodos do módulo é sempre self, isto é, a referência para o canvas em questão. Portanto, é recomendado o uso de chamada de método de Lua utilizando o : (colon operator) como em:

myCanvas:drawRect('fill', 10, 10, 100, 100)

As coordenadas passadas para os métodos são sempre relativas ao ponto mais à esquerda e ao topo do canvas (0,0), como é comum entre sistemas gráficos.

Segue um exemplo simples para ilustrar o uso do módulo canvas:

width, height = canvas:attrSize()   -- pega as dimensões da região
canvas:drawLine(0,0, width,height)  -- desenha uma linha cruzando o canvas
img = canvas:new('image.png')       -- carrega 'image.png' para um novo canvas
canvas:compose(100, 100, img)       -- desenha a imagem na posição (100,100) da região
canvas:flush()                      -- atualiza a região do documento NCL

O resultado visual é o seguinte:

Funções

A partir do objeto canvas é possível criar novos objetos gráficos e combiná-los através de operações de composição.

Há dois tipos de construtores.

O primeiro instancia um canvas com o tamanho especificado:

canvas:new (width, height)

Onde:

• width: [number] Largura do canvas.
• height: [number] Altura do canvas.

Inicialmente os pixels são todos transparentes.

O segundo instancia um canvas cujo conteúdo é a imagem passada como parâmetro:

canvas:new (image_path)

Onde:

• image_path: [string] Caminho da imagem.

O novo canvas mantém os aspectos de transparência da imagem original.

Retorna as dimensões do canvas.

Retorna:

• width: [number] Largura do canvas.
• height: [number] Altura do canvas.

Não é possível alterar as dimensões de um canvas instanciado, portanto para este método, apenas a leitura é disponível.

Acessa o atributo de cor do canvas.

As primitivas gráficas utilizam a cor deste atributo do canvas. As cores são descritas em RGBA, onde A varia de 0 (totalmente transparente) a 255 (totalmente opaco). O valor inicial do atributo é 0,0,0,255 (preto).

Os valores de retorno (em caso de leitura) e argumentos (em caso de escrita), são:

• R: [number] Componente vermelha da cor.
• G: [number] Componente verde da cor.
• B: [number] Componente azul da cor.
• A: [number] Componente alpha da cor.

A assinatura do método para leitura é:

canvas:attrColor () --> R, G, B, A

A assinatura do método para escrita é:

canvas:attrColor (R, G, B, A)

Também é possível passar diretamente o nome da cor:

canvas:attrColor (color_name, A)

Onde:

• color_name: [string] Nome da cor.
• A: [number] Componente alpha da cor.

Uma das 16 cores NCL pré-definidas pode ser passada:

'white', 'aqua', 'lime', 'yellow', 'red',   'fuchsia', 'purple', 'maroon',
'blue',  'navy', 'teal', 'green',  'olive', 'silver',  'gray',   'black'

Em ambos os casos, caso A não seja passado, é assumido o valor 255 (opaco).

Acessa o atributo que limita a área do canvas para desenho.

Acessa o atributo de recorte do canvas.

Quando o canvas é composto sobre outro, apenas a região de recorte é copiada para o canvas de destino.

O valor inicial é o canvas inteiro.

Os valores de retorno (em caso de leitura) e argumentos (em caso de escrita), são:

• x: [number] Coordenada x da área limitada.
• y: [number] Coordenada y da área limitada.
• width: [number] Largura da área limitada.
• height: [number] Altura da área limitada.

A assinatura do método para leitura é:

canvas:attrCrop () --> x, y, width, height

A assinatura do método para escrita é:

canvas:attrCrop (x, y, width, height)

Acessa o atributo de fonte do canvas.

O tamanho é em pixels e representa a altura máxima de uma linha escrita com a fonte escolhida. Os estilos possíveis são: 'bold', 'italic' ou 'bold-italic'. O valor nil assume que nenhum dos estilos será usado. Qualquer valor passado não suportado deve obrigatoriamente gerar um erro. O valor inicial da fonte é indeterminado.

Os valores de retorno (em caso de leitura) e argumentos (em caso de escrita), são:

• face: [string] Nome da fonte.
• size: [number] Tamanho da fonte.
• style: [string] Estilo da fonte.

A assinatura do método para leitura é:

canvas:attrFont () --> face, size, style

A assinatura do método para escrita é:

canvas:attrFont (face, size, style)

Desenha uma linha com extremidades em (x1,y1) e (x2,y2).

Desenha um retângulo no canvas.

Desenha o texto passado na posição (x,y) do canvas.

Retorna as dimensões do texto passado.

Faz a composição pixel a pixel entre dois canvas.

O canvas passado como src é desenhado sobre o canvas em uso (canvas) na posição passada.

Recebe:

• x: [number] Posição x da composição.
• y: [number] Posição y da composição.
• canvas_src: [canvas] Canvas a ser composto sobre canvas.

Após a operação, o canvas de destino canvas possui o resultado da composição e o canvas src não sofre qualquer alteração.

Atualiza o canvas após operações de desenho e de composição.

É suficiente chamá-la apenas uma vez após uma sequência de operações.