src/cpuinfo/SDL_simd.h
changeset 11984 987c5dc71309
child 12503 806492103856
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/src/cpuinfo/SDL_simd.h	Mon May 21 11:34:57 2018 -0400
     1.3 @@ -0,0 +1,88 @@
     1.4 +/*
     1.5 +  Simple DirectMedia Layer
     1.6 +  Copyright (C) 1997-2018 Sam Lantinga <slouken@libsdl.org>
     1.7 +
     1.8 +  This software is provided 'as-is', without any express or implied
     1.9 +  warranty.  In no event will the authors be held liable for any damages
    1.10 +  arising from the use of this software.
    1.11 +
    1.12 +  Permission is granted to anyone to use this software for any purpose,
    1.13 +  including commercial applications, and to alter it and redistribute it
    1.14 +  freely, subject to the following restrictions:
    1.15 +
    1.16 +  1. The origin of this software must not be misrepresented; you must not
    1.17 +     claim that you wrote the original software. If you use this software
    1.18 +     in a product, an acknowledgment in the product documentation would be
    1.19 +     appreciated but is not required.
    1.20 +  2. Altered source versions must be plainly marked as such, and must not be
    1.21 +     misrepresented as being the original software.
    1.22 +  3. This notice may not be removed or altered from any source distribution.
    1.23 +*/
    1.24 +
    1.25 +#include "SDL.h"
    1.26 +#include "../SDL_internal.h"
    1.27 +
    1.28 +/**
    1.29 + * \brief Report the alignment this system needs for SIMD allocations.
    1.30 + *
    1.31 + * This will return the minimum number of bytes to which a pointer must be
    1.32 + *  aligned to be compatible with SIMD instructions on the current machine.
    1.33 + *  For example, if the machine supports SSE only, it will return 16, but if
    1.34 + *  it supports AVX-512F, it'll return 64 (etc). This only reports values for
    1.35 + *  instruction sets SDL knows about, so if your SDL build doesn't have
    1.36 + *  SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
    1.37 + *  not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
    1.38 + *  Plan accordingly.
    1.39 + */
    1.40 +extern size_t SDL_SIMDGetAlignment(void);
    1.41 +
    1.42 +/**
    1.43 + * \brief Allocate memory in a SIMD-friendly way.
    1.44 + *
    1.45 + * This will allocate a block of memory that is suitable for use with SIMD
    1.46 + *  instructions. Specifically, it will be properly aligned and padded for
    1.47 + *  the system's supported vector instructions.
    1.48 + *
    1.49 + * The memory returned will be padded such that it is safe to read or write
    1.50 + *  an incomplete vector at the end of the memory block. This can be useful
    1.51 + *  so you don't have to drop back to a scalar fallback at the end of your
    1.52 + *  SIMD processing loop to deal with the final elements without overflowing
    1.53 + *  the allocated buffer.
    1.54 + *
    1.55 + * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free()
    1.56 + *  or delete[], etc.
    1.57 + *
    1.58 + * Note that SDL will only deal with SIMD instruction sets it is aware of;
    1.59 + *  for example, SDL 2.0.8 knows that SSE wants 16-byte vectors
    1.60 + *  (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't
    1.61 + *  know that AVX-512 wants 64. To be clear: if you can't decide to use an
    1.62 + *  instruction set with an SDL_Has*() function, don't use that instruction
    1.63 + *  set with memory allocated through here.
    1.64 + *
    1.65 + * SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't
    1.66 + *  out of memory.
    1.67 + *
    1.68 + *  \param len The length, in bytes, of the block to allocated. The actual
    1.69 + *             allocated block might be larger due to padding, etc.
    1.70 + * \return Pointer to newly-allocated block, NULL if out of memory.
    1.71 + *
    1.72 + * \sa SDL_SIMDAlignment
    1.73 + * \sa SDL_SIMDFree
    1.74 + */
    1.75 +extern void * SDL_SIMDAlloc(const size_t len);
    1.76 +
    1.77 +/**
    1.78 + * \brief Deallocate memory obtained from SDL_SIMDAlloc
    1.79 + *
    1.80 + * It is not valid to use this function on a pointer from anything but
    1.81 + *  SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
    1.82 + *  SDL_malloc, memalign, new[], etc.
    1.83 + *
    1.84 + * However, SDL_SIMDFree(NULL) is a legal no-op.
    1.85 + *
    1.86 + * \sa SDL_SIMDAlloc
    1.87 + */
    1.88 +extern void SDL_SIMDFree(void *ptr);
    1.89 +
    1.90 +/* vi: set ts=4 sw=4 expandtab: */
    1.91 +