Home | History | Annotate | Download | only in scriptc 
      1 /*
      2  * Copyright (C) 2011-2012 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17  /*! \mainpage notitle
     18   *
     19   * Renderscript is a high-performance runtime that provides graphics rendering and
     20   * compute operations at the native level. Renderscript code is compiled on devices
     21   * at runtime to allow platform-independence as well.
     22   * This reference documentation describes the Renderscript runtime APIs, which you
     23   * can utilize to write Renderscript code in C99. The Renderscript header
     24   * files are automatically included for you, except for the rs_graphics.rsh header. If
     25   * you are doing graphics rendering, include the graphics header file like this:
     26   *
     27   * <code>#include "rs_graphics.rsh"</code>
     28   *
     29   * To use Renderscript, you need to utilize the Renderscript runtime APIs documented here
     30   * as well as the Android framework APIs for Renderscript.
     31   * For documentation on the Android framework APIs, see the <a target="_parent" href=
     32   * "http://developer.android.com/reference/android/renderscript/package-summary.html">
     33   * android.renderscript</a> package reference.
     34   * For more information on how to develop with Renderscript and how the runtime and
     35   * Android framework APIs interact, see the <a target="_parent" href=
     36   * "http://developer.android.com/guide/topics/renderscript/index.html">Renderscript
     37   * developer guide</a> and the <a target="_parent" href=
     38   * "http://developer.android.com/resources/samples/RenderScript/index.html">
     39   * Renderscript samples</a>.
     40   */
     41 
     42 /** @file rs_core.rsh
     43  *  \brief todo-jsams
     44  *
     45  *  todo-jsams
     46  *
     47  */
     48 
     49 #ifndef __RS_CORE_RSH__
     50 #define __RS_CORE_RSH__
     51 
     52 #define _RS_RUNTIME extern
     53 
     54 #include "rs_types.rsh"
     55 #include "rs_allocation.rsh"
     56 #include "rs_atomic.rsh"
     57 #include "rs_cl.rsh"
     58 #include "rs_debug.rsh"
     59 #include "rs_element.rsh"
     60 #include "rs_math.rsh"
     61 #include "rs_matrix.rsh"
     62 #include "rs_object.rsh"
     63 #include "rs_quaternion.rsh"
     64 #include "rs_sampler.rsh"
     65 #include "rs_time.rsh"
     66 
     67 /**
     68  * Send a message back to the client.  Will not block and returns true
     69  * if the message was sendable and false if the fifo was full.
     70  * A message ID is required.  Data payload is optional.
     71  */
     72 extern bool __attribute__((overloadable))
     73     rsSendToClient(int cmdID);
     74 /**
     75  * \overload
     76  */
     77 extern bool __attribute__((overloadable))
     78     rsSendToClient(int cmdID, const void *data, uint len);
     79 /**
     80  * Send a message back to the client, blocking until the message is queued.
     81  * A message ID is required.  Data payload is optional.
     82  */
     83 extern void __attribute__((overloadable))
     84     rsSendToClientBlocking(int cmdID);
     85 /**
     86  * \overload
     87  */
     88 extern void __attribute__((overloadable))
     89     rsSendToClientBlocking(int cmdID, const void *data, uint len);
     90 
     91 
     92 /**
     93  * Launch order hint for rsForEach calls.  This provides a hint to the system to
     94  * determine in which order the root function of the target is called with each
     95  * cell of the allocation.
     96  *
     97  * This is a hint and implementations may not obey the order.
     98  */
     99 enum rs_for_each_strategy {
    100     RS_FOR_EACH_STRATEGY_SERIAL,
    101     RS_FOR_EACH_STRATEGY_DONT_CARE,
    102     RS_FOR_EACH_STRATEGY_DST_LINEAR,
    103     RS_FOR_EACH_STRATEGY_TILE_SMALL,
    104     RS_FOR_EACH_STRATEGY_TILE_MEDIUM,
    105     RS_FOR_EACH_STRATEGY_TILE_LARGE
    106 };
    107 
    108 
    109 /**
    110  * Structure to provide extra information to a rsForEach call.  Primarly used to
    111  * restrict the call to a subset of cells in the allocation.
    112  */
    113 typedef struct rs_script_call {
    114     enum rs_for_each_strategy strategy;
    115     uint32_t xStart;
    116     uint32_t xEnd;
    117     uint32_t yStart;
    118     uint32_t yEnd;
    119     uint32_t zStart;
    120     uint32_t zEnd;
    121     uint32_t arrayStart;
    122     uint32_t arrayEnd;
    123 } rs_script_call_t;
    124 
    125 /**
    126  * Make a script to script call to launch work. One of the input or output is
    127  * required to be a valid object. The input and output must be of the same
    128  * dimensions.
    129  * API 10-13
    130  *
    131  * @param script The target script to call
    132  * @param input The allocation to source data from
    133  * @param output the allocation to write date into
    134  * @param usrData The user definied params to pass to the root script.  May be
    135  *                NULL.
    136  * @param sc Extra control infomation used to select a sub-region of the
    137  *           allocation to be processed or suggest a walking strategy.  May be
    138  *           NULL.
    139  *
    140  *  */
    141 #if !defined(RS_VERSION) || (RS_VERSION < 14)
    142 extern void __attribute__((overloadable))
    143     rsForEach(rs_script script, rs_allocation input,
    144               rs_allocation output, const void * usrData,
    145               const rs_script_call_t *sc);
    146 /**
    147  * \overload
    148  */
    149 extern void __attribute__((overloadable))
    150     rsForEach(rs_script script, rs_allocation input,
    151               rs_allocation output, const void * usrData);
    152 #else
    153 
    154 /**
    155  * Make a script to script call to launch work. One of the input or output is
    156  * required to be a valid object. The input and output must be of the same
    157  * dimensions.
    158  * API 14+
    159  *
    160  * @param script The target script to call
    161  * @param input The allocation to source data from
    162  * @param output the allocation to write date into
    163  * @param usrData The user definied params to pass to the root script.  May be
    164  *                NULL.
    165  * @param usrDataLen The size of the userData structure.  This will be used to
    166  *                   perform a shallow copy of the data if necessary.
    167  * @param sc Extra control infomation used to select a sub-region of the
    168  *           allocation to be processed or suggest a walking strategy.  May be
    169  *           NULL.
    170  *
    171  */
    172 extern void __attribute__((overloadable))
    173     rsForEach(rs_script script, rs_allocation input, rs_allocation output,
    174               const void * usrData, size_t usrDataLen, const rs_script_call_t *);
    175 /**
    176  * \overload
    177  */
    178 extern void __attribute__((overloadable))
    179     rsForEach(rs_script script, rs_allocation input, rs_allocation output,
    180               const void * usrData, size_t usrDataLen);
    181 /**
    182  * \overload
    183  */
    184 extern void __attribute__((overloadable))
    185     rsForEach(rs_script script, rs_allocation input, rs_allocation output);
    186 #endif
    187 
    188 
    189 
    190 #undef _RS_RUNTIME
    191 
    192 #endif
    193