Finale PDK Framework 0.79
Lua Power for Finale Music Software
Loading...
Searching...
No Matches
ff_rawdata.h
1/*
2 * File: ff_rawdata.h
3 * Author: Robert Patterson
4 *
5 * Created on February 14, 2026
6 */
7
8#ifndef FF_RAWDATA_H
9#define FF_RAWDATA_H
10
11#include <string>
12#include <vector>
13
14#include "ff_base.h"
15
60class FCRawData : public __FCBase
61{
62private:
63 EXTAG _tag;
64 EDataID _id;
65 EVERSION _version;
66 std::vector<unsigned char> _data;
67
68public:
69 const char* ClassName() const override { return "FCRawData"; }
70 const PDKFRAMEWORK_CLASSID GetClassID() const override { return FCID_RAWDATA; }
71
76 FCRawData();
77
86 bool AssignTarget(__FCBaseData* pSource);
87
92 EXTAG GetTag() const { return _tag; }
93
98 void SetTag(EXTAG tag) { _tag = tag; }
99
104 EVERSION GetVersion() const { return _version; }
105
110 void SetVersion(EVERSION version) { _version = version; }
111
119 static EXTAG MakeOtherTag(const std::string& tagChars, int incisPerStruct = 1);
120
121#ifdef PDK_FRAMEWORK_LUAFRIENDLY_CPP
123 static int MakeOtherTag_CFunc(lua_State* L)
124 {
125 const int numArgs = lua_gettop(L);
126 const std::string tagChars = luabridge::Stack<std::string>::get(L, 1) LB3(.value());
127 const int incisPerStruct = (numArgs < 2) ? 1 : luabridge::Stack<int>::get(L, 2) LB3(.value());
128 luabridge::Stack<EXTAG>::push(L, MakeOtherTag(tagChars, incisPerStruct)) LB3(.throw_on_error());
129 return 1;
130 }
131#endif
132
140 static EXTAG MakeDetailTag(const std::string& tagChars, int incisPerStruct = 1);
141
142#ifdef PDK_FRAMEWORK_LUAFRIENDLY_CPP
144 static int MakeDetailTag_CFunc(lua_State* L)
145 {
146 const int numArgs = lua_gettop(L);
147 const std::string tagChars = luabridge::Stack<std::string>::get(L, 1) LB3(.value());
148 const int incisPerStruct = (numArgs < 2) ? 1 : luabridge::Stack<int>::get(L, 2) LB3(.value());
149 luabridge::Stack<EXTAG>::push(L, MakeDetailTag(tagChars, incisPerStruct)) LB3(.throw_on_error());
150 return 1;
151 }
152#endif
153
161 static EXTAG MakeEntryDetailTag(const std::string& tagChars, int incisPerStruct = 1);
162
163#ifdef PDK_FRAMEWORK_LUAFRIENDLY_CPP
165 static int MakeEntryDetailTag_CFunc(lua_State* L)
166 {
167 const int numArgs = lua_gettop(L);
168 const std::string tagChars = luabridge::Stack<std::string>::get(L, 1) LB3(.value());
169 const int incisPerStruct = (numArgs < 2) ? 1 : luabridge::Stack<int>::get(L, 2) LB3(.value());
170 luabridge::Stack<EXTAG>::push(L, MakeEntryDetailTag(tagChars, incisPerStruct)) LB3(.throw_on_error());
171 return 1;
172 }
173#endif
174
179 void SetTagAsOther(const std::string& tagChars, int incisPerStruct = 1);
180
181#ifdef PDK_FRAMEWORK_LUAFRIENDLY_CPP
183 int SetTagAsOther_CFunc(lua_State* L)
184 {
185 const int numArgs = lua_gettop(L);
186 // argument 1 is `this`
187 const std::string tagChars = luabridge::Stack<std::string>::get(L, 2) LB3(.value());
188 const int incisPerStruct = (numArgs < 3) ? 1 : luabridge::Stack<int>::get(L, 3) LB3(.value());
189 SetTagAsOther(tagChars, incisPerStruct);
190 return 0;
191 }
192#endif
193
198 void SetTagAsDetail(const std::string& tagChars, int incisPerStruct = 1);
199
200#ifdef PDK_FRAMEWORK_LUAFRIENDLY_CPP
202 int SetTagAsDetail_CFunc(lua_State* L)
203 {
204 const int numArgs = lua_gettop(L);
205 // argument 1 is `this`
206 const std::string tagChars = luabridge::Stack<std::string>::get(L, 2) LB3(.value());
207 const int incisPerStruct = (numArgs < 3) ? 1 : luabridge::Stack<int>::get(L, 3) LB3(.value());
208 SetTagAsDetail(tagChars, incisPerStruct);
209 return 0;
210 }
211#endif
212
217 void SetTagAsEntryDetail(const std::string& tagChars, int incisPerStruct = 1);
218
219#ifdef PDK_FRAMEWORK_LUAFRIENDLY_CPP
221 int SetTagAsEntryDetail_CFunc(lua_State* L)
222 {
223 const int numArgs = lua_gettop(L);
224 // argument 1 is `this`
225 const std::string tagChars = luabridge::Stack<std::string>::get(L, 2) LB3(.value());
226 const int incisPerStruct = (numArgs < 3) ? 1 : luabridge::Stack<int>::get(L, 3) LB3(.value());
227 SetTagAsEntryDetail(tagChars, incisPerStruct);
228 return 0;
229 }
230#endif
231
236 void SetDataIDAsOther(CMPER cmper, twobyte inci = 0);
237
238#ifdef PDK_FRAMEWORK_LUAFRIENDLY_CPP
240 int SetDataIDAsOther_CFunc(lua_State* L)
241 {
242 const int numArgs = lua_gettop(L);
243 // argument 1 is `this`
244 const CMPER cmper = luabridge::Stack<CMPER>::get(L, 2) LB3(.value());
245 const twobyte inci = (numArgs < 3) ? 0 : luabridge::Stack<twobyte>::get(L, 3) LB3(.value());
246 SetDataIDAsOther(cmper, inci);
247 return 0;
248 }
249#endif
250
258 void SetDataIDAsDetail(CMPER cmper1, CMPER cmper2, twobyte inci = 0);
259
260#ifdef PDK_FRAMEWORK_LUAFRIENDLY_CPP
262 int SetDataIDAsDetail_CFunc(lua_State* L)
263 {
264 const int numArgs = lua_gettop(L);
265 // argument 1 is `this`
266 const CMPER cmper1 = luabridge::Stack<CMPER>::get(L, 2) LB3(.value());
267 const CMPER cmper2 = luabridge::Stack<CMPER>::get(L, 3) LB3(.value());
268 const twobyte inci = (numArgs < 4) ? 0 : luabridge::Stack<twobyte>::get(L, 4) LB3(.value());
269 SetDataIDAsDetail(cmper1, cmper2, inci);
270 return 0;
271 }
272#endif
273
280 void SetDataIDAsEntryDetail(ENTNUM entryNumber, twobyte inci = 0);
281
282#ifdef PDK_FRAMEWORK_LUAFRIENDLY_CPP
284 int SetDataIDAsEntryDetail_CFunc(lua_State* L)
285 {
286 const int numArgs = lua_gettop(L);
287 // argument 1 is `this`
288 const ENTNUM entryNumber = luabridge::Stack<ENTNUM>::get(L, 2) LB3(.value());
289 const twobyte inci = (numArgs < 3) ? 0 : luabridge::Stack<twobyte>::get(L, 3) LB3(.value());
290 SetDataIDAsEntryDetail(entryNumber, inci);
291 return 0;
292 }
293#endif
294
299 void SetTargetAsOther(const std::string& tagChars, CMPER cmper, twobyte inci = 0, int incisPerStruct = 1);
300
301#ifdef PDK_FRAMEWORK_LUAFRIENDLY_CPP
303 int SetTargetAsOther_CFunc(lua_State* L)
304 {
305 const int numArgs = lua_gettop(L);
306 const std::string tagChars = luabridge::Stack<std::string>::get(L, 2) LB3(.value());
307 const CMPER cmper = luabridge::Stack<CMPER>::get(L, 3) LB3(.value());
308 const twobyte inci = (numArgs < 4) ? 0 : luabridge::Stack<twobyte>::get(L, 4) LB3(.value());
309 const int incisPerStruct = (numArgs < 5) ? 1 : luabridge::Stack<int>::get(L, 5) LB3(.value());
310 SetTargetAsOther(tagChars, cmper, inci, incisPerStruct);
311 return 0;
312 }
313#endif
314
319 void SetTargetAsDetail(const std::string& tagChars, CMPER cmper1, CMPER cmper2, twobyte inci = 0, int incisPerStruct = 1);
320
321#ifdef PDK_FRAMEWORK_LUAFRIENDLY_CPP
323 int SetTargetAsDetail_CFunc(lua_State* L)
324 {
325 const int numArgs = lua_gettop(L);
326 const std::string tagChars = luabridge::Stack<std::string>::get(L, 2) LB3(.value());
327 const CMPER cmper1 = luabridge::Stack<CMPER>::get(L, 3) LB3(.value());
328 const CMPER cmper2 = luabridge::Stack<CMPER>::get(L, 4) LB3(.value());
329 const twobyte inci = (numArgs < 5) ? 0 : luabridge::Stack<twobyte>::get(L, 5) LB3(.value());
330 const int incisPerStruct = (numArgs < 6) ? 1 : luabridge::Stack<int>::get(L, 6) LB3(.value());
331 SetTargetAsDetail(tagChars, cmper1, cmper2, inci, incisPerStruct);
332 return 0;
333 }
334#endif
335
340 void SetTargetAsEntryDetail(const std::string& tagChars, ENTNUM entryNumber, twobyte inci = 0, int incisPerStruct = 1);
341
342#ifdef PDK_FRAMEWORK_LUAFRIENDLY_CPP
344 int SetTargetAsEntryDetail_CFunc(lua_State* L)
345 {
346 const int numArgs = lua_gettop(L);
347 const std::string tagChars = luabridge::Stack<std::string>::get(L, 2) LB3(.value());
348 const ENTNUM entryNumber = luabridge::Stack<ENTNUM>::get(L, 3) LB3(.value());
349 const twobyte inci = (numArgs < 4) ? 0 : luabridge::Stack<twobyte>::get(L, 4) LB3(.value());
350 const int incisPerStruct = (numArgs < 5) ? 1 : luabridge::Stack<int>::get(L, 5) LB3(.value());
351 SetTargetAsEntryDetail(tagChars, entryNumber, inci, incisPerStruct);
352 return 0;
353 }
354#endif
355
360 CMPER GetOtherCmper() const { return _id.other.cmper; }
361
366 twobyte GetOtherInci() const { return _id.other.inci; }
367
374 CMPER GetDetailCmper1() const { return _id.detail.cmper1; }
375
382 CMPER GetDetailCmper2() const { return _id.detail.cmper2; }
383
388 twobyte GetDetailInci() const { return _id.detail.inci; }
389
396 ENTNUM GetEntryDetailEntryNumber() const { return _id.entryDetail.entryNumber; }
397
402 twobyte GetEntryDetailInci() const { return _id.entryDetail.inci; }
403
408 ETAG GetTagDataType() const { return static_cast<ETAG>((_tag >> 16) & 0xffff); }
409
414 std::string GetTagChars() const;
415
422 int GetIncisPerStruct() const;
423
428 void ClearData();
429
434 int GetByteCount() const { return static_cast<int>(_data.size()); }
435
440 std::string GetData() const;
441
446 void SetData(const std::string& data);
447
452 std::vector<int> GetByteTable() const;
453
458 void SetByteTable(const std::vector<int>& table);
459
464 std::vector<int> GetTwoByteTable() const;
465
470 void SetTwoByteTable(const std::vector<int>& table);
471
476 std::vector<int> GetFourByteTable() const;
477
482 void SetFourByteTable(const std::vector<int>& table);
483
492 int GetFourByte(int byteOffset) const;
493
502 bool SetFourByte(int byteOffset, int value);
503
508 bool Load();
509
514 bool LoadWithSize(int byteCount);
515
522 bool LoadWithExpectedSize(int expectedByteCount);
523
528 bool Exists() const;
529
538 bool LoadNextInci();
539
544 bool Save() const;
545
550 bool Create();
551
556 bool Delete() const;
557};
558
559#endif /* FF_RAWDATA_H */
Base class for all data-related classes (that handles Finale data).
Definition ff_base.h:677
Base class for the Finale Framework classes.
Definition ff_base.h:71
PDKFRAMEWORK_CLASSID
Constants for the GetClassID method.
Definition ff_base.h:84
Generic low-level Enigma data accessor for one data record.
Definition ff_rawdata.h:61
bool AssignTarget(__FCBaseData *pSource)
Copies EXTAG, EDataID, and Enigma version from a __FCBaseData object.
Definition finaleframework.cpp:272
std::string GetData() const
Returns the stored payload as a binary string.
Definition finaleframework.cpp:374
void ClearData()
Clears the stored raw payload.
Definition finaleframework.cpp:369
void SetTag(EXTAG tag)
Sets the EXTAG value.
Definition ff_rawdata.h:98
twobyte GetEntryDetailInci() const
Returns entry detail inci from EDataID.
Definition ff_rawdata.h:402
bool Exists() const
Returns true if the current target exists.
Definition finaleframework.cpp:562
const PDKFRAMEWORK_CLASSID GetClassID() const override
Returns the internal class ID for the PDK Framework class. This is implemented mostly because Lua has...
Definition ff_rawdata.h:70
bool LoadWithSize(int byteCount)
Loads the record using a caller-provided byte size.
Definition finaleframework.cpp:536
EXTAG GetTag() const
Returns the EXTAG value.
Definition ff_rawdata.h:92
bool Save() const
Saves current payload to current EXTAG/EDataID location.
Definition finaleframework.cpp:592
FCRawData()
The constructor.
Definition finaleframework.cpp:267
void SetData(const std::string &data)
Sets the stored payload from a binary string.
Definition finaleframework.cpp:380
void SetFourByteTable(const std::vector< int > &table)
Sets payload from little-endian signed 32-bit values.
Definition finaleframework.cpp:469
int GetByteCount() const
Returns the number of stored bytes.
Definition ff_rawdata.h:434
EVERSION GetVersion() const
Returns the Enigma version used in FX_*EData calls.
Definition ff_rawdata.h:104
void SetTagAsOther(const std::string &tagChars, int incisPerStruct=1)
Sets current tag using MakeOtherTag.
Definition finaleframework.cpp:299
twobyte GetOtherInci() const
Returns the "other" inci value from EDataID.
Definition ff_rawdata.h:366
bool Load()
Loads the record by first querying its raw size.
Definition finaleframework.cpp:515
CMPER GetDetailCmper1() const
Returns detail cmper1 from EDataID.
Definition ff_rawdata.h:374
void SetDataIDAsOther(CMPER cmper, twobyte inci=0)
Sets the EDataID as an "other" ID.
Definition finaleframework.cpp:314
std::vector< int > GetTwoByteTable() const
Returns payload as little-endian 16-bit values (0..65535).
Definition finaleframework.cpp:410
CMPER GetOtherCmper() const
Returns the "other" cmper value from EDataID.
Definition ff_rawdata.h:360
int GetIncisPerStruct() const
Returns the configured incidences-per-struct implied by current tag data type.
Definition finaleframework.cpp:364
void SetDataIDAsDetail(CMPER cmper1, CMPER cmper2, twobyte inci=0)
Sets the EDataID as a "detail" ID.
Definition finaleframework.cpp:321
bool LoadNextInci()
Increments current inci and attempts to load the next record.
Definition finaleframework.cpp:569
ENTNUM GetEntryDetailEntryNumber() const
Returns entry number from EDataID.
Definition ff_rawdata.h:396
static EXTAG MakeOtherTag(const std::string &tagChars, int incisPerStruct=1)
Makes an EXTAG for other data from two tag characters and optional incis-per-struct.
Definition finaleframework.cpp:281
static EXTAG MakeEntryDetailTag(const std::string &tagChars, int incisPerStruct=1)
Makes an EXTAG for entry detail data from two tag characters and optional incis-per-struct.
Definition finaleframework.cpp:293
std::string GetTagChars() const
Returns the two-character low-word tag code of the current EXTAG.
Definition finaleframework.cpp:354
int GetFourByte(int byteOffset) const
Reads a signed 32-bit value at the given byte offset.
Definition finaleframework.cpp:487
void SetByteTable(const std::vector< int > &table)
Sets payload bytes from integer values (0..255).
Definition finaleframework.cpp:394
void SetTagAsEntryDetail(const std::string &tagChars, int incisPerStruct=1)
Sets current tag using MakeEntryDetailTag.
Definition finaleframework.cpp:309
std::vector< int > GetFourByteTable() const
Returns payload as little-endian signed 32-bit values.
Definition finaleframework.cpp:443
twobyte GetDetailInci() const
Returns detail inci from EDataID.
Definition ff_rawdata.h:388
ETAG GetTagDataType() const
Returns the top-word data type of the current EXTAG (for example edOther).
Definition ff_rawdata.h:408
const char * ClassName() const override
Returns the name of the class, for diagnostic purposes. This method MUST be overwritten in each child...
Definition ff_rawdata.h:69
bool Create()
Creates a new record with current payload.
Definition finaleframework.cpp:598
bool LoadWithExpectedSize(int expectedByteCount)
Loads the record and verifies an exact byte size match.
Definition finaleframework.cpp:550
static EXTAG MakeDetailTag(const std::string &tagChars, int incisPerStruct=1)
Makes an EXTAG for detail data from two tag characters and optional incis-per-struct.
Definition finaleframework.cpp:287
bool Delete() const
Deletes the current EXTAG/EDataID record.
Definition finaleframework.cpp:604
void SetTargetAsDetail(const std::string &tagChars, CMPER cmper1, CMPER cmper2, twobyte inci=0, int incisPerStruct=1)
Convenience helper: sets tag and EDataID for a "detail" target in one call.
Definition finaleframework.cpp:342
bool SetFourByte(int byteOffset, int value)
Writes a signed 32-bit value at the given byte offset.
Definition finaleframework.cpp:500
void SetTwoByteTable(const std::vector< int > &table)
Sets payload from little-endian 16-bit values (0..65535).
Definition finaleframework.cpp:426
void SetVersion(EVERSION version)
Sets the Enigma version used in FX_*EData calls.
Definition ff_rawdata.h:110
void SetTargetAsOther(const std::string &tagChars, CMPER cmper, twobyte inci=0, int incisPerStruct=1)
Convenience helper: sets tag and EDataID for an "other" target in one call.
Definition finaleframework.cpp:336
void SetDataIDAsEntryDetail(ENTNUM entryNumber, twobyte inci=0)
Sets the EDataID as an "entry detail" ID.
Definition finaleframework.cpp:329
CMPER GetDetailCmper2() const
Returns detail cmper2 from EDataID.
Definition ff_rawdata.h:382
void SetTagAsDetail(const std::string &tagChars, int incisPerStruct=1)
Sets current tag using MakeDetailTag.
Definition finaleframework.cpp:304
std::vector< int > GetByteTable() const
Returns payload bytes as integer values (0..255).
Definition finaleframework.cpp:385
void SetTargetAsEntryDetail(const std::string &tagChars, ENTNUM entryNumber, twobyte inci=0, int incisPerStruct=1)
Convenience helper: sets tag and EDataID for an "entry detail" target in one call.
Definition finaleframework.cpp:348