Agregação e o sibling aggregator¶

Uma árvore tem que descrever dois grafos. Esta página é sobre o segundo — e sobre a única regra que decide o que cada composite coleta.

Por que duas hierarquias¶

O Node View do Harmony carrega dois grafos de conexão ao mesmo tempo:

Hierarquia	Cor	Conecta	Significa
Input / Transform	🟢 verde	peg → seus filhos	"este move aquele"
Output / Composite	🔵 azul	comp ← o que o alimenta	"este compõe aquele"

Elas não são a mesma árvore. Um peg pode dirigir várias composições distintas, e um composite pode juntar coisas que nenhum peg único move.

A árvore de staging é uma árvore — tem exatamente um tipo de parentesco. Então o OSA a usa para o grafo verde, onde a indentação já significa o que você quer que signifique: uma linha filha é um nó filho.

Isso deixa o grafo azul sem indentação para morar. A resposta dele é posição entre os irmãos.

O sibling aggregator¶

Um composite sem green container agrega os irmãos abaixo dele.

Isso é um sibling aggregator (agregador de irmãos). Ele não tem escopo próprio para olhar dentro, então olha lista abaixo.

Comp-1        ← starts block 1
Peg-1         ← feeds Comp-1 … but see below: what enters is Comp-2's output
  Comp-2      ← starts an inner block; its output IS Peg-1's output
  Drawing-1   ← feeds Comp-2
  Drawing-2   ← feeds Comp-2
Drawing-3     ← feeds Comp-1
Comp-3        ← ENDS block 1, starts block 2
Drawing-4     ← feeds Comp-3
Drawing-5     ← feeds Comp-3

Lendo isso em voz alta: um comp abre um bloco, tudo depois dele flui para dentro, e o próximo comp no mesmo nível fecha o bloco e abre um novo.

Um peg não alimenta um comp — quem alimenta é a saída da hierarquia dele

Peg-1 é um transform, não uma imagem. O que chega em Comp-1 é o resultado de tudo que está sob Peg-1, e esse resultado sai de Comp-2 — o comp dentro do escopo de Peg-1, que já juntou Drawing-1 e Drawing-2.

Então o fio é Comp-2 → Comp-1. Peg-1 está no grafo verde; ele nunca aparece no azul.

Tire Comp-2 e Peg-1 não tem comp para falar por ele — aí Drawing-1 e Drawing-2 sobem (bubble up) e são ligados em Comp-1 individualmente, como duas entradas em vez de uma. Essa é toda a diferença entre um peg com comp e um peg sem comp, e está coberta em O que um container entrega na saída.

E um segundo comp dentro de Peg-1 significaria duas saídas chegando em Comp-1 — uma por bloco:

Comp-1
Peg-1              ← now hands Comp-1 TWO outputs
  Comp-2           ← block A → its output goes to Comp-1
  Drawing-1        → feeds Comp-2
  Comp-2b          ← block B: closes A, opens its own
  Drawing-2        → feeds Comp-2b
                   ← Comp-2b's output ALSO goes to Comp-1

Cada bloco que termina dentro de um container sobe como sua própria saída, na ordem da árvore. Então o número de fios que chegam em Comp-1 vindos de Peg-1 é exatamente o número de blocos que Peg-1 fechou — um comp, um fio; dois comps, dois fios; nenhum comp, um fio por drawing.

O que quebra a corrente¶

Outro composite no mesmo nível. É a única coisa que faz isso.

Quando a varredura encontra um segundo comp entre os mesmos irmãos, ela descarrega o bloco atual e começa um novo. Não há marcador para definir nem opção para marcar: a presença do segundo comp é a fronteira.

É por isso que você pode montar uma cena como uma lista plana de irmãos e ainda assim tirar dela várias composições separadas — você as separa colocando um comp onde cada grupo deve terminar.

A regra que decide filhos vs irmãos¶

Só green containers criam escopo, e existem exatamente dois: Peg e Group.

Slot	O comp agrega	Por quê
`C` sozinho	irmãos abaixo	nada além de um ponto de agregação
`D-C`	irmãos abaixo	sem green container, sem escopo
`BD-C`	irmãos abaixo	um backdrop é visual — ele não possui nós
`BD-D-C`	irmãos abaixo	o mesmo: o backdrop não muda nada na fiação
`P-C`, `G-C`	filhos	o green container cria um escopo interno
`P-D-C`, `G-D-C`	filhos	o mesmo
`BD-P-C`, `BD-P-G-D-C`	filhos	quem faz isso é o peg; o backdrop só desenha uma caixa

Um backdrop nunca muda quem agrega

Esta é a que as pessoas erram, e vale dizer sem rodeio: BD é visual. BG=BD-C agrega irmãos exatamente como um C puro, porque não existe conexão verde entre o backdrop e o comp para o comp coletar filhos por ela. Só P ou G transformam um comp em agregador de filhos.

Super node com Peg (ou Group) + Comp¶

Agora o caso que você monta todo dia.

Um slot com um green container e um comp — hero=P-C, hero=BD-P-G-C — faz o comp agregar seus filhos imediatos, na ordem da árvore…

…até o primeiro filho que também é um comp. Esse filho começa um novo bloco de sibling aggregator, e tudo depois dele pertence a aquele bloco.

hero=P-C            ← green scope; its comp collects the children below
├── arm=D           → feeds hero-C
├── leg=D           → feeds hero-C
├── fx=C            ← a comp among the children: block boundary
├── glow=D          → feeds fx-C
└── dust=D          → feeds fx-C

hero-C recebe arm e leg. fx-C recebe glow e dust, e a saída do próprio fx-C é o que continua subindo.

Essa é toda a linguagem de composição: um green container abre um escopo, e um comp dentro dele coleta até o próximo comp mandar parar.

O que um container entrega na saída¶

O container	A saída dele
tem um comp interno	uma saída única — o comp, ou o último efeito depois dele
não tem comp interno	multi-saída: cada drawing lá dentro sobe (bubbles up)

Um peg sem comp não junta nada. Ele entrega ao pai uma lista, e cada item é ligado individualmente ao comp do pai.

SuperNode=P-D-C
├── Peg-1  (P only, no Comp)
│   ├── Drawing-A
│   └── Drawing-B
└── Drawing-C

Peg-1 retorna [Drawing-A, Drawing-B], então SuperNode-C recebe quatro entradas:

Porta	Entrada
3	o drawing do próprio `SuperNode`
2	`Drawing-A` (subiu de Peg-1)
1	`Drawing-B` (subiu de Peg-1)
0	`Drawing-C`

Coloque um comp no peg e esses dois colapsam em uma entrada só. Essa é a diferença prática entre Peg-1=P e Peg-1=P-C, e geralmente é a razão de um grafo ter mais fios do que você esperava.

Ordem das portas¶

O grafo azul tem uma direção, e ela é fixa:

Porta	Renderiza	Fica
Porta N (a mais alta)	à frente	à esquerda no Node View
Porta 0 (a mais baixa)	atrás	à direita no Node View

Então o elemento mais à esquerda no Node View está por cima no render, e o mais à direita está no fundo. Dentro de um super node, o drawing do próprio slot ocupa a porta da frente e os filhos ficam nas de baixo, da esquerda para a direita.

É por isso também que o Wide Bus põe o topo da sua árvore à esquerda: ordem da árvore, ordem das portas e ordem de render são a mesma ordem, lida do mesmo jeito.

Lendo isso na árvore¶

Você não precisa simular nada disso na cabeça — a coluna Details já diz o que cada linha constrói, e a regra acima diz o que o comp dela vai coletar:

BACKGROUND      (Backdrop > Peg > Comp)     ← green scope: collects its children
  sky           (Read)                       → feeds BACKGROUND-C
  clouds        (Read)                       → feeds BACKGROUND-C
EFFECTS         (Backdrop > Peg > Comp > Effects)

Se um comp está coletando as coisas erradas, só há duas perguntas a fazer: existe um green container nesse slot? e existe outro comp acima dele entre os mesmos irmãos?