[RFC-002] Standardize where to return or pass outward by reference

[TheCurle]

Currently the engine uses a large mixture of the two.

We should standardize where to:

bool ProcessStuff(const Input& in, Output& out);

or:

Output ProcessStuff(const Input& in);

because the current system just doesn't work.

[dpeter99]

I haven't written any code that does pass out by reference. I think we should return by value as that is easier to understand. And where we do want to pass back values (multiple outputs or allocation avoidance) we should clearly mark the parameter as an out perameter

[TheCurle]

I use pass out-by-reference for instances where allocating and copying the necessary data multiple times isn't feasible, or where allocating, passing and then immediately destroying the data would be too heavy on heap allocations. For example, the shader compiler:

/**
     * Compile the shader module from the given source input, storing into the given output.
     * @param input source input, data and metadata, and compiler options
     * @param out the binary data if successful, errors if unsuccessful
     */
    void Compile(const CompilerInput& input, CompilerOutput& out);

This could return a CompilerOutput*, but the lifetime of the object is literally the caller + the line after the caller, and it will never be used again. That's a heavy allocation.

Pass out-by-reference allows stack memory of the call site to be used for the allocation, which is better on memory, and doesn't involve a heap allocate and delete, which may even be faster for a hot path like the shader compilation (which is done lazily)

[dpeter99]

Yeah that sounds fine to me

[TheCurle]

Herein lies the dilemma. We need to be sure between the two of us where the line that makes this okay lies.

If it comes down to developer discretion, then that's fair enough - as long as we're on the same page.