1/*
2 * Copyright (C) 2008 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#ifndef bts_COMPACT_MAT_EM_H
18#define bts_COMPACT_MAT_EM_H
19
20/* ---- includes ----------------------------------------------------------- */
21
22#include "b_BasicEm/Int16Arr.h"
23
24/* ---- related objects  --------------------------------------------------- */
25
26/* ---- typedefs ----------------------------------------------------------- */
27
28/* ---- constants ---------------------------------------------------------- */
29
30/* data format version number */
31#define bts_COMPACT_MAT_VERSION 100
32
33/* ---- object definition -------------------------------------------------- */
34
35/** Compact Matrix
36 *  This object represents a general nxm Matrix that stores its values in
37 *  bit-packs of fixed size. Rows are encoded individually to yield
38 *  maximum accuracy for the given number of bits. The matrix takes sparseness
39 *  into account.
40 *
41 *  Use this object for memory efficient storage of large matrices.
42 */
43struct bts_CompactMat
44{
45
46	/* ---- private data --------------------------------------------------- */
47
48	/* ---- public data ---------------------------------------------------- */
49
50	/* width (columns) of matrix */
51	uint32 widthE;
52
53	/* height (rows) of matrix */
54	uint32 heightE;
55
56	/* bits per value */
57	uint32 bitsPerValueE;
58
59	/* 16 bit words per row including row-header (always even) */
60	uint32 wordsPerRowE;
61
62	/* maximum of ( 16 + factorExp + normBits ) for all rows (this value can be negative!) */
63	int32 maxRowBitsE;
64
65	/** Composite data array
66	 *  Encoding per row:
67	 *  (int16) 'offs' offset of row-vector (0 when row is not sparse)
68	 *  (int16) 'size' effective size of row vector (= widthE when row is not sparse)
69	 *  (int16) 'factorMan' mantisse of factor
70	 *  (int16) 'factorExp' exponent of factor
71	 *  (int16) 'normBits' norm bits of row vector
72	 *  (int16), (int16), ... packed data
73	 *  Each row has the effective length of 'wordsPerRowE'
74	 *  wordsPerRowE is always even -> rows are 32bit-aligned
75	 */
76	struct bbs_Int16Arr cpsArrE;
77
78	/** temorary array used for exponents */
79	struct bbs_Int16Arr expArrE;
80
81};
82
83/* ---- associated objects ------------------------------------------------- */
84
85/* ---- external functions ------------------------------------------------- */
86
87/* ---- \ghd{ constructor/destructor } ------------------------------------- */
88
89/** initializes object */
90void bts_CompactMat_init( struct bbs_Context* cpA,
91					      struct bts_CompactMat* ptrA );
92
93/** destroys object */
94void bts_CompactMat_exit( struct bbs_Context* cpA,
95					      struct bts_CompactMat* ptrA );
96
97/* ---- \ghd{ operators } -------------------------------------------------- */
98
99/* copies matrix */
100void bts_CompactMat_copy( struct bbs_Context* cpA,
101					      struct bts_CompactMat* ptrA,
102						  const struct bts_CompactMat* srcPtrA );
103
104/* ---- \ghd{ query functions } -------------------------------------------- */
105
106/* ---- \ghd{ modify functions } ------------------------------------------- */
107
108/** allocates matrix */
109void bts_CompactMat_create( struct bbs_Context* cpA,
110						    struct bts_CompactMat* ptrA,
111						    uint32 widthA,
112						    uint32 heightA,
113						    uint32 bitsA,
114							uint32 maxRowSizeA,
115				            struct bbs_MemSeg* mspA );
116
117/* ---- \ghd{ memory I/O } ------------------------------------------------- */
118
119/** size object needs when written to memory */
120uint32 bts_CompactMat_memSize( struct bbs_Context* cpA,
121							   const struct bts_CompactMat* ptrA );
122
123/** writes object to memory; returns number of bytes written */
124uint32 bts_CompactMat_memWrite( struct bbs_Context* cpA,
125							    const struct bts_CompactMat* ptrA,
126							    uint16* memPtrA );
127
128/** reads object from memory; returns number of bytes read */
129uint32 bts_CompactMat_memRead( struct bbs_Context* cpA,
130							   struct bts_CompactMat* ptrA,
131							   const uint16* memPtrA,
132				               struct bbs_MemSeg* mspA );
133
134/* ---- \ghd{ exec functions } --------------------------------------------- */
135
136/** Maps vector inVec to outVec (overflow-safe)
137 *  Memory areas of vectors may not overlap
138 *  Function executes reasonably fast with maximum possible accuracy
139 *  outExpPtrA - exponent to output vector values
140 */
141void bts_CompactMat_map( struct bbs_Context* cpA,
142						 const struct bts_CompactMat* ptrA,
143						 const int16* inVecA,
144						 int16* outVecA,
145						 int16* outExpPtrA );
146
147#endif /* bts_COMPACT_MAT_EM_H */
148
149