renderer/Scene: Scene paints modifications

[lpogic]

For now, the only ways to modify scene paints are Result Scene::push(Paint* paint) and Result Scene::clear(bool free) methods. It is still possible to get scene paints via list<Paint*>& Scene::paints() and modify the list directly, but this is probably not the best way to do it because it breaks the reference counting.

My suggestion is to add some methods for more control over the paints in the scene, for example:

• Result Scene::remove(Paint* paint) - removes paint from scene
• Result Scene::insert(size_t index, Paint* paint) - inserts paint into scene at index

[hermet]

See also: #2598

[hermet]

@lpogic Hello, this is my suggestion. Please let me know if this doesn't compatible with you. Thanks.

Addition

Result Scene::remove(Paint* paint);  //Remove the paint from the scene
Paint* Scene::remove(size_t idx);       //Remove the paint associated with the idx
size_t Scene::count();  //Return the current paint count
const Paint* Scene::get(size_t idx) const;   //Temporary access to the paint associated with the idx.
size_t Scene::insert(Paint* paint, size_t idx = SIZE_MAX);  //Insert the paint at a specific position, moving the paints behind it accordingly. Using SIZE_MAX will append the paint to the end of the paint list. API also returns the paint index.

Remove

Result Scene::push(Paint* paint);
std::list<Paint*>& Scene::paints();
Result Scene::clear(bool free = true);

[lpogic]

@hermet Such an API would be enough for me. Only thing is will there be control over paint free during remove? I manage memory externally and it's important to me that there is a way to disable automatic free.

[hermet]

@lpogic Please check Paint features:

    /**
     * @brief Increment the reference count for the Paint instance.
     *
     * This method increases the reference count of the Paint object, allowing shared ownership and control over its lifetime.
     *
     * @return The updated reference count after the increment by 1.
     *
     * @warning Please ensure that each call to ref() is paired with a corresponding call to unref() to prevent a dangling instance.
     *
     * @see Paint::unref()
     * @see Paint::refCnt()
     *
     * @since 1.0
     */
    uint8_t ref() noexcept;

    /**
     * @brief Decrement the reference count for the Paint instance.
     *
     * This method decreases the reference count of the Paint object by 1.
     * If the reference count reaches zero and the @p free flag is set to true, the Paint instance is automatically deleted.
     *
     * @param[in] free Flag indicating whether to delete the Paint instance when the reference count reaches zero.
     *
     * @return The updated reference count after the decrement.
     *
     * @see Paint::ref()
     * @see Paint::refCnt()
     *
     * @since 1.0
     */
    uint8_t unref(bool free = true) noexcept;

    /**
     * @brief Retrieve the current reference count of the Paint instance.
     *
     * This method provides the current reference count, allowing the user to check the shared ownership state of the Paint object.
     *
     * @return The current reference count of the Paint instance.
     *
     * @see Paint::ref()
     * @see Paint::unref()
     *
     * @since 1.0
     */
    uint8_t refCnt() const noexcept;

[lpogic]

@hermet In fact, this way I can ensure that the reference counter does not reset to zero until I decrement it externally. Thanks for the tip!