scriptc/rs_for_each.rsh

/*
 * Copyright (C) 2015 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

// Don't edit this file!  It is auto-generated by frameworks/rs/api/generate.sh.

/*
 * rs_for_each.rsh: TODO Add documentation
 *
 * TODO Add documentation
 */

#ifndef RENDERSCRIPT_RS_FOR_EACH_RSH
#define RENDERSCRIPT_RS_FOR_EACH_RSH

/*
 * rs_for_each_strategy_t: Launch order hint for rsForEach calls
 *
 * Launch order hint for rsForEach calls.  This provides a hint to the system to
 * determine in which order the root function of the target is called with each
 * cell of the allocation.
 *
 * This is a hint and implementations may not obey the order.
 */
typedef enum rs_for_each_strategy {
    RS_FOR_EACH_STRATEGY_SERIAL = 0,
    RS_FOR_EACH_STRATEGY_DONT_CARE = 1,
    RS_FOR_EACH_STRATEGY_DST_LINEAR = 2,
    RS_FOR_EACH_STRATEGY_TILE_SMALL = 3,
    RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4,
    RS_FOR_EACH_STRATEGY_TILE_LARGE = 5
} rs_for_each_strategy_t;

/*
 * rs_kernel_context: Opaque handle to RenderScript kernel invocation context
 *
 * TODO
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
typedef const struct rs_kernel_context_t * rs_kernel_context;
#endif

/*
 * rs_script_call_t: Provides extra information to a rsForEach call
 *
 * Structure to provide extra information to a rsForEach call.  Primarly used to
 * restrict the call to a subset of cells in the allocation.
 */
typedef struct rs_script_call {
    rs_for_each_strategy_t strategy;
    uint32_t xStart;
    uint32_t xEnd;
    uint32_t yStart;
    uint32_t yEnd;
    uint32_t zStart;
    uint32_t zEnd;
    uint32_t arrayStart;
    uint32_t arrayEnd;
} rs_script_call_t;

/*
 * Make a script to script call to launch work. One of the input or output is
 * required to be a valid object. The input and output must be of the same
 * dimensions.
 *
 * Parameters:
 *   script: The target script to call
 *   input: The allocation to source data from
 *   output: the allocation to write date into
 *   usrData: The user defined params to pass to the root script.  May be NULL.
 *   sc: Extra control infomation used to select a sub-region of the allocation to be processed or suggest a walking strategy.  May be NULL.
 *   usrDataLen: The size of the userData structure.  This will be used to perform a shallow copy of the data if necessary.
 */
#if !defined(RS_VERSION) || (RS_VERSION <= 13)
extern void __attribute__((overloadable))
    rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData,
              const rs_script_call_t* sc);
#endif

#if !defined(RS_VERSION) || (RS_VERSION <= 13)
extern void __attribute__((overloadable))
    rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData);
#endif

#if (defined(RS_VERSION) && (RS_VERSION >= 14) && (RS_VERSION <= 20))
extern void __attribute__((overloadable))
    rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData,
              size_t usrDataLen, const rs_script_call_t* sc);
#endif

#if (defined(RS_VERSION) && (RS_VERSION >= 14) && (RS_VERSION <= 20))
extern void __attribute__((overloadable))
    rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData,
              size_t usrDataLen);
#endif

#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern void __attribute__((overloadable))
    rsForEach(rs_script script, rs_allocation input, rs_allocation output);
#endif

/*
 * rsGetArray0: Index in the Array0 dimension for the specified context
 *
 * Returns the index in the Array0 dimension of the cell being processed,
 * as specified by the supplied context.
 *
 * This context is created when a kernel is launched and updated at each
 * iteration.  It contains common characteristics of the allocations being
 * iterated over and rarely used indexes, like the Array0 index.
 *
 * You can access the context by adding a rs_kernel_context argument to your
 * kernel function.  E.g.
 * short RS_KERNEL myKernel(short value, uint32_t x, rs_kernel_context context) {
 *   // The current index in the common x, y, z, w dimensions are accessed by
 *   // adding these variables as arguments.  For the more rarely used indexes
 *   // to the other dimensions, extract them from the context:
 *   uint32_t index_a0 = rsGetArray0(context);
 *   //...
 * }
 *
 * This function returns 0 if the Array0 dimension is not present.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
    rsGetArray0(rs_kernel_context ctxt);
#endif

/*
 * rsGetArray1: Index in the Array1 dimension for the specified context
 *
 * Returns the index in the Array1 dimension of the cell being processed,
 * as specified by the supplied context.  See rsGetArray0() for an explanation
 * of the context.
 *
 * Returns 0 if the Array1 dimension is not present.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
    rsGetArray1(rs_kernel_context ctxt);
#endif

/*
 * rsGetArray2: Index in the Array2 dimension for the specified context
 *
 * Returns the index in the Array2 dimension of the cell being processed,
 * as specified by the supplied context.  See rsGetArray0() for an explanation
 * of the context.
 *
 * Returns 0 if the Array2 dimension is not present.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
    rsGetArray2(rs_kernel_context ctxt);
#endif

/*
 * rsGetArray3: Index in the Array3 dimension for the specified context
 *
 * Returns the index in the Array3 dimension of the cell being processed,
 * as specified by the supplied context.  See rsGetArray0() for an explanation
 * of the context.
 *
 * Returns 0 if the Array3 dimension is not present.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
    rsGetArray3(rs_kernel_context ctxt);
#endif

/*
 * rsGetDimArray0: Size of the Array0 dimension for the specified context
 *
 * Returns the size of the Array0 dimension for the specified context.
 * See rsGetDimX() for an explanation of the context.
 *
 * Returns 0 if the Array0 dimension is not present.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
    rsGetDimArray0(rs_kernel_context ctxt);
#endif

/*
 * rsGetDimArray1: Size of the Array1 dimension for the specified context
 *
 * Returns the size of the Array1 dimension for the specified context.
 * See rsGetDimX() for an explanation of the context.
 *
 * Returns 0 if the Array1 dimension is not present.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
    rsGetDimArray1(rs_kernel_context ctxt);
#endif

/*
 * rsGetDimArray2: Size of the Array2 dimension for the specified context
 *
 * Returns the size of the Array2 dimension for the specified context.
 * See rsGetDimX() for an explanation of the context.
 *
 * Returns 0 if the Array2 dimension is not present.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
    rsGetDimArray2(rs_kernel_context ctxt);
#endif

/*
 * rsGetDimArray3: Size of the Array3 dimension for the specified context
 *
 * Returns the size of the Array3 dimension for the specified context.
 * See rsGetDimX() for an explanation of the context.
 *
 * Returns 0 if the Array3 dimension is not present.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
    rsGetDimArray3(rs_kernel_context ctxt);
#endif

/*
 * rsGetDimHasFaces: Presence of more than one face for the specified context
 *
 * If the context refers to a cubemap, this function returns true if there's
 * more than one face present.  In all other cases, it returns false.
 * See rsGetDimX() for an explanation of the context.
 *
 * rsAllocationGetDimFaces() is similar but returns 0 or 1 instead of a bool.
 *
 * Returns: Returns true if more than one face is present, false otherwise.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern bool __attribute__((overloadable))
    rsGetDimHasFaces(rs_kernel_context ctxt);
#endif

/*
 * rsGetDimLod: Number of levels of detail for the specified context
 *
 * Returns the number of levels of detail for the specified context.
 * This is useful for mipmaps.  See rsGetDimX() for an explanation of the context.
 * Returns 0 if Level of Detail is not used.
 *
 * rsAllocationGetDimLOD() is similar but returns 0 or 1 instead the actual
 * number of levels.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
    rsGetDimLod(rs_kernel_context ctxt);
#endif

/*
 * rsGetDimX: Size of the X dimension for the specified context
 *
 * Returns the size of the X dimension for the specified context.
 *
 * This context is created when a kernel is launched.  It contains common
 * characteristics of the allocations being iterated over by the kernel in
 * a very efficient structure.  It also contains rarely used indexes.
 *
 * You can access it by adding a rs_kernel_context argument to your kernel
 * function.  E.g.
 * int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {
 *   uint32_t size = rsGetDimX(context); //...
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
    rsGetDimX(rs_kernel_context ctxt);
#endif

/*
 * rsGetDimY: Size of the Y dimension for the specified context
 *
 * Returns the size of the X dimension for the specified context.
 * See rsGetDimX() for an explanation of the context.
 *
 * Returns 0 if the Y dimension is not present.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
    rsGetDimY(rs_kernel_context ctxt);
#endif

/*
 * rsGetDimZ: Size of the Z dimension for the specified context
 *
 * Returns the size of the Z dimension for the specified context.
 * See rsGetDimX() for an explanation of the context.
 *
 * Returns 0 if the Z dimension is not present.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
    rsGetDimZ(rs_kernel_context ctxt);
#endif

/*
 * rsGetFace: Coordinate of the Face for the specified context
 *
 * Returns the face on which the cell being processed is found, as specified
 * by the supplied context.  See rsGetArray0() for an explanation of the context.
 *
 * Returns RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X if the face dimension is not
 * present.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern rs_allocation_cubemap_face __attribute__((overloadable))
    rsGetFace(rs_kernel_context ctxt);
#endif

/*
 * rsGetLod: Index in the Levels of Detail dimension for the specified context.
 *
 * Returns the index in the Levels of Detail dimension of the cell being
 * processed, as specified by the supplied context.  See rsGetArray0() for
 * an explanation of the context.
 *
 * Returns 0 if the Levels of Detail dimension is not present.
 */
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
    rsGetLod(rs_kernel_context ctxt);
#endif

#endif // RENDERSCRIPT_RS_FOR_EACH_RSH