1/*
2 * Copyright (C) 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/** @file rs_element.rsh
18 *  \brief Element routines
19 *
20 *
21 */
22
23#ifndef __RS_ELEMENT_RSH__
24#define __RS_ELEMENT_RSH__
25
26// New API's
27#if (defined(RS_VERSION) && (RS_VERSION >= 16))
28
29/**
30 * Elements could be simple, such as an int or a float, or a
31 * structure with multiple sub elements, such as a collection of
32 * floats, float2, float4. This function returns zero for simple
33 * elements or the number of sub-elements otherwise.
34 *
35 * @param e element to get data from
36 * @return number of sub-elements in this element
37 */
38extern uint32_t __attribute__((overloadable))
39    rsElementGetSubElementCount(rs_element e);
40
41/**
42 * For complex elements, this function will return the
43 * sub-element at index
44 *
45 * @param e element to get data from
46 * @param index index of the sub-element to return
47 * @return sub-element in this element at given index
48 */
49extern rs_element __attribute__((overloadable))
50    rsElementGetSubElement(rs_element, uint32_t index);
51
52/**
53 * For complex elements, this function will return the length of
54 * sub-element name at index
55 *
56 * @param e element to get data from
57 * @param index index of the sub-element to return
58 * @return length of the sub-element name including the null
59 *         terminator (size of buffer needed to write the name)
60 */
61extern uint32_t __attribute__((overloadable))
62    rsElementGetSubElementNameLength(rs_element e, uint32_t index);
63
64/**
65 * For complex elements, this function will return the
66 * sub-element name at index
67 *
68 * @param e element to get data from
69 * @param index index of the sub-element
70 * @param name array to store the name into
71 * @param nameLength length of the provided name array
72 * @return number of characters actually written, excluding the
73 *         null terminator
74 */
75extern uint32_t __attribute__((overloadable))
76    rsElementGetSubElementName(rs_element e, uint32_t index, char *name, uint32_t nameLength);
77
78/**
79 * For complex elements, some sub-elements could be statically
80 * sized arrays. This function will return the array size for
81 * sub-element at index
82 *
83 * @param e element to get data from
84 * @param index index of the sub-element
85 * @return array size of sub-element in this element at given
86 *         index
87 */
88extern uint32_t __attribute__((overloadable))
89    rsElementGetSubElementArraySize(rs_element e, uint32_t index);
90
91/**
92 * This function specifies the location of a sub-element within
93 * the element
94 *
95 * @param e element to get data from
96 * @param index index of the sub-element
97 * @return offset in bytes of sub-element in this element at
98 *         given index
99 */
100extern uint32_t __attribute__((overloadable))
101    rsElementGetSubElementOffsetBytes(rs_element e, uint32_t index);
102
103/**
104 * Returns the size of element in bytes
105 *
106 * @param e element to get data from
107 * @return total size of the element in bytes
108 */
109extern uint32_t __attribute__((overloadable))
110    rsElementGetBytesSize(rs_element e);
111
112/**
113 * Returns the element's data type
114 *
115 * @param e element to get data from
116 * @return element's data type
117 */
118extern rs_data_type __attribute__((overloadable))
119    rsElementGetDataType(rs_element e);
120
121/**
122 * Returns the element's data kind
123 *
124 * @param e element to get data from
125 * @return element's data size
126 */
127extern rs_data_kind __attribute__((overloadable))
128    rsElementGetDataKind(rs_element e);
129
130/**
131 * Returns the element's vector size
132 *
133 * @param e element to get data from
134 * @return length of the element vector (for float2, float3,
135 *         etc.)
136 */
137extern uint32_t __attribute__((overloadable))
138    rsElementGetVectorSize(rs_element e);
139
140#endif // (defined(RS_VERSION) && (RS_VERSION >= 16))
141
142#endif // __RS_ELEMENT_RSH__
143
144