Documentation on Accelerated Rendering

[J. Landman Gay]

On 4/29/17 9:56 PM, Sannyasin Brahmanathaswami via use-livecode wrote:
> My question is:  where is the documentation for AcceleratedRendering
>
> -- exactly what does it do? (don't worry, if the explanation is very technical.. .let me see it!)
> -- when does it help
> -- what contexts may there be where it could actually impede performance?

I have been wanting to know that for years. I have the general idea but 
I want to know exactly what each command or property does. How does 
layerMode interact with rendering and when should I set it? (I used it 
incorrectly and submitted a spurious bug report, but I'm still not clear 
on why I was wrong.)

Here is what (I think) I do know:

AcceleratedRendering creates an offscreen buffer for objects that have a 
non-static layerMode. It then only needs to redraw the particular object 
instead of the whole card when you move that object, which is much 
faster. If it is a scrolling object (group or field) then the layermode 
should be set to "scrolling". If you are going to drag things around or 
use the "move" command, then those objects should be set to "dynamic". 
If the object doesn't move, or only moves very rarely, its layermode 
should stay at the default "static" and no buffer is created.

The compositorTileSize, compositorType, and compositorCacheLimit all 
affect the size and behavior of the buffer(s). The defaults provided 
have always worked for me so I don't change them. I'm not sure how I 
would add up the memory requirements for a set of moving objects so I 
stick with the defaults.

I'm guessing it would impede performance if it is creating buffers for 
objects that aren't really going to move. You'd have the overhead of the 
buffer creation and some decrease in available memory. And from my 
incorrect bug report, I gather you shouldn't change layermode on the fly.

What I would like to know is:

- What does layerMode tell the engine, and when is it read? I think it 
tells the engine to create a buffer for the object. I had read a long 
time ago that it would help to reset the layermode to static if the 
object was done moving, but there should have been a caveat: don't reset 
if the object will move again later, because in that case you want to 
preserve the existing buffer. That seems to imply that resetting 
layermode to static will dump the buffer. Is that right?

- When set to true, what does acceleratedRendering actually do? Is it 
effectively a command to scan every object on the card and create 
buffers? Does it scan more than just the current card?

- Is it okay to turn it on and off as needed? Are there disadvantages to 
that, assuming the objects won't be moving any more? Can I turn it on at 
the beginning of a handler and turn it off at the end if those objects 
won't be moving any more?

- When I turn it off, does it dump all the buffers? I think it does.

- What does it do between card changes? Does it keep old buffers until 
the cache limit is hit?

-- 
Jacqueline Landman Gay         |     jacque at hyperactivesw.com
HyperActive Software           |     http://www.hyperactivesw.com