Memory Allocation

mental ray's memory allocation functions replace the standard malloc packages found on most systems. They have built-in functions for memory leak tracing and consistency checks, and handle errors automatically. Shaders should always use these functions and not malloc or similar libc functions directly.

    void *mi_mem_allocate(
        const int     size)

Accepts one argument specifying the size of the memory to allocate. A pointer to the allocated memory is returned. If the allocation fails, an error is reported automatically, and mental ray tries to recover memory or aborts if this fails. This call is guaranteed to return a valid pointer, or not to return at all. The allocated memory is zeroed. This and most other mem_* functions use locking and should therefore not be used in time-critical places to prevent multithreading efficiency from dropping through the floor. See page efficiency for details on the effect of locks on efficiency. A good place for memory allocation is init shaders.

    void *mi_mem_test_allocate(
        const int     size)

Accepts one argument specifying the size of the memory to allocate. A pointer to the allocated memory is returned. The allocated memory is zeroed. If the allocation fails, a null pointer is returned. This call is used when it is acceptable for an allocation to fail.

    void *mi_mem_reallocate(
        void * const  mem,
        const int     size)

Changes the size of an allocated block of memory. There are two arguments: a pointer to the old block of memory, and the requested new size of that block. A pointer to the new block is returned, which may be different from the pointer to the old block. If the old pointer was a null pointer, mi_mem_reallocate behaves like mi_mem_allocate. If the new size is zero, mi_mem_reallocate behaves like mi_mem_release, and returns a null pointer. If there is an allocation error, an error is reported and raylib is aborted. Like mi_mem_allocate, mi_mem_reallocate never returns if the re-allocation fails. If the block grows, the extra bytes are zeroed.

    void *mi_mem_test_reallocate(
        void * const  mem,
        const int     size)

Change the size of an allocated block of memory. There are two arguments: a pointer to the old block of memory, and the requested new size of that block. A pointer to the new block is returned, which may be different from the pointer to the old block. If the old pointer was a null pointer, mi_mem_test_reallocate behaves like mi_mem_test_allocate. If the new size is zero, mi_mem_test_reallocate behaves like mi_mem_release, and returns a null pointer. If the block grows, the extra bytes are zeroed. If there is an allocation error, a null pointer is returned. This call is used when it is acceptable for an allocation to fail.

    void mi_mem_release(
        void * const  mem)

Frees a block of memory. There is one argument: the address of the block. If a null pointer is passed, nothing is done. There is no return value. After releasing memory it may no longer be accessed.

    char *mi_mem_strdup(
        const char    *text)

Allocates enough memory to hold text including the trailing null byte, copies text into the allocated memory, and returns it. The returned string must be released with mi_mem_release. This function is especially useful to pass strings to functions in the mi_api_ family, which all expect allocated strings (and will automatically handle the required mi_mem_release).