src/cpuinfo/SDL_simd.h
author Ryan C. Gordon <icculus@icculus.org>
Tue, 25 Sep 2018 17:04:47 -0400
branchSDL-ryan-batching-renderer
changeset 12236 80367def8b68
parent 11984 987c5dc71309
child 12503 806492103856
permissions -rw-r--r--
render: Move non-batching flushes to different place.

This lets us batch up a few commands that are all related to the same API
call.
icculus@11984
     1
/*
icculus@11984
     2
  Simple DirectMedia Layer
icculus@11984
     3
  Copyright (C) 1997-2018 Sam Lantinga <slouken@libsdl.org>
icculus@11984
     4
icculus@11984
     5
  This software is provided 'as-is', without any express or implied
icculus@11984
     6
  warranty.  In no event will the authors be held liable for any damages
icculus@11984
     7
  arising from the use of this software.
icculus@11984
     8
icculus@11984
     9
  Permission is granted to anyone to use this software for any purpose,
icculus@11984
    10
  including commercial applications, and to alter it and redistribute it
icculus@11984
    11
  freely, subject to the following restrictions:
icculus@11984
    12
icculus@11984
    13
  1. The origin of this software must not be misrepresented; you must not
icculus@11984
    14
     claim that you wrote the original software. If you use this software
icculus@11984
    15
     in a product, an acknowledgment in the product documentation would be
icculus@11984
    16
     appreciated but is not required.
icculus@11984
    17
  2. Altered source versions must be plainly marked as such, and must not be
icculus@11984
    18
     misrepresented as being the original software.
icculus@11984
    19
  3. This notice may not be removed or altered from any source distribution.
icculus@11984
    20
*/
icculus@11984
    21
icculus@11984
    22
#include "SDL.h"
icculus@11984
    23
#include "../SDL_internal.h"
icculus@11984
    24
icculus@11984
    25
/**
icculus@11984
    26
 * \brief Report the alignment this system needs for SIMD allocations.
icculus@11984
    27
 *
icculus@11984
    28
 * This will return the minimum number of bytes to which a pointer must be
icculus@11984
    29
 *  aligned to be compatible with SIMD instructions on the current machine.
icculus@11984
    30
 *  For example, if the machine supports SSE only, it will return 16, but if
icculus@11984
    31
 *  it supports AVX-512F, it'll return 64 (etc). This only reports values for
icculus@11984
    32
 *  instruction sets SDL knows about, so if your SDL build doesn't have
icculus@11984
    33
 *  SDL_HasAVX512F(), then it might return 16 for the SSE support it sees and
icculus@11984
    34
 *  not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
icculus@11984
    35
 *  Plan accordingly.
icculus@11984
    36
 */
icculus@11984
    37
extern size_t SDL_SIMDGetAlignment(void);
icculus@11984
    38
icculus@11984
    39
/**
icculus@11984
    40
 * \brief Allocate memory in a SIMD-friendly way.
icculus@11984
    41
 *
icculus@11984
    42
 * This will allocate a block of memory that is suitable for use with SIMD
icculus@11984
    43
 *  instructions. Specifically, it will be properly aligned and padded for
icculus@11984
    44
 *  the system's supported vector instructions.
icculus@11984
    45
 *
icculus@11984
    46
 * The memory returned will be padded such that it is safe to read or write
icculus@11984
    47
 *  an incomplete vector at the end of the memory block. This can be useful
icculus@11984
    48
 *  so you don't have to drop back to a scalar fallback at the end of your
icculus@11984
    49
 *  SIMD processing loop to deal with the final elements without overflowing
icculus@11984
    50
 *  the allocated buffer.
icculus@11984
    51
 *
icculus@11984
    52
 * You must free this memory with SDL_FreeSIMD(), not free() or SDL_free()
icculus@11984
    53
 *  or delete[], etc.
icculus@11984
    54
 *
icculus@11984
    55
 * Note that SDL will only deal with SIMD instruction sets it is aware of;
icculus@11984
    56
 *  for example, SDL 2.0.8 knows that SSE wants 16-byte vectors
icculus@11984
    57
 *  (SDL_HasSSE()), and AVX2 wants 32 bytes (SDL_HasAVX2()), but doesn't
icculus@11984
    58
 *  know that AVX-512 wants 64. To be clear: if you can't decide to use an
icculus@11984
    59
 *  instruction set with an SDL_Has*() function, don't use that instruction
icculus@11984
    60
 *  set with memory allocated through here.
icculus@11984
    61
 *
icculus@11984
    62
 * SDL_AllocSIMD(0) will return a non-NULL pointer, assuming the system isn't
icculus@11984
    63
 *  out of memory.
icculus@11984
    64
 *
icculus@11984
    65
 *  \param len The length, in bytes, of the block to allocated. The actual
icculus@11984
    66
 *             allocated block might be larger due to padding, etc.
icculus@11984
    67
 * \return Pointer to newly-allocated block, NULL if out of memory.
icculus@11984
    68
 *
icculus@11984
    69
 * \sa SDL_SIMDAlignment
icculus@11984
    70
 * \sa SDL_SIMDFree
icculus@11984
    71
 */
icculus@11984
    72
extern void * SDL_SIMDAlloc(const size_t len);
icculus@11984
    73
icculus@11984
    74
/**
icculus@11984
    75
 * \brief Deallocate memory obtained from SDL_SIMDAlloc
icculus@11984
    76
 *
icculus@11984
    77
 * It is not valid to use this function on a pointer from anything but
icculus@11984
    78
 *  SDL_SIMDAlloc(). It can't be used on pointers from malloc, realloc,
icculus@11984
    79
 *  SDL_malloc, memalign, new[], etc.
icculus@11984
    80
 *
icculus@11984
    81
 * However, SDL_SIMDFree(NULL) is a legal no-op.
icculus@11984
    82
 *
icculus@11984
    83
 * \sa SDL_SIMDAlloc
icculus@11984
    84
 */
icculus@11984
    85
extern void SDL_SIMDFree(void *ptr);
icculus@11984
    86
icculus@11984
    87
/* vi: set ts=4 sw=4 expandtab: */
icculus@11984
    88