ScummVM API documentation
cc_static_array.h
1/* ScummVM - Graphic Adventure Engine
2 *
3 * ScummVM is the legal property of its developers, whose names
4 * are too numerous to list here. Please refer to the COPYRIGHT
5 * file distributed with this source distribution.
6 *
7 * This program is free software: you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation, either version 3 of the License, or
10 * (at your option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this program. If not, see <http://www.gnu.org/licenses/>.
19 *
20 */
21
22//=============================================================================
23//
24// CCStaticArray manages access to an array of script objects,
25// where an element's size counted by script's bytecode may differ from the
26// real element size in the engine's memory.
27// The purpose of this is to remove size restriction from the engine's structs
28// exposed to scripts.
29//
30// FIXME: [ivan-mogilko] the above was meant to work, but in reality it doesn't
31// and won't, at least not without some extra workarounds.
32// The problem that I missed here is following:
33// when the script compiler is told to get an Nth element of a global struct
34// array, such as character[n], it calculates the memory address as
35// array address + sizeof(Character) * n.
36// If this address is used for the read/write operations, these ops can be
37// intercepted by interpreter and remapped into the real fields
38// (see IScriptObject::ReadN, WriteN interface)
39// But if this address is used IN POINTER COMPARISON, then we cannot do
40// anything. And if our real struct in the engine is stored on a different
41// relative memory offset than one expected by compiler, then this pointer
42// comparison will fail, e.g. script expression like
43// if (player == character[n])
44//
45// NOTE: on the other hand, similar effect could be achieved by separating
46// object data into two or more structs, where "base" structs are stored in
47// the exposed arrays (part of API), while extending structs are stored
48// separately. This is more an issue of engine data design.
49//
50//=============================================================================
51
52#ifndef AGS_ENGINE_AC_DYNOBJ_STATIC_ARRAY_H
53#define AGS_ENGINE_AC_DYNOBJ_STATIC_ARRAY_H
54
55#include "ags/engine/ac/dynobj/cc_ags_dynamic_object.h"
56
57namespace AGS3 {
58
59
61public:
62 ~CCStaticArray() override {}
63
64 void Create(IScriptObject *mgr, size_t elem_script_size, size_t elem_mem_size, size_t elem_count = SIZE_MAX /*unknown*/);
65
66 inline IScriptObject *GetObjectManager() const {
67 return _mgr;
68 }
69
70 // Legacy support for reading and writing object values by their relative offset
71 inline void *GetElementPtr(void *address, intptr_t legacy_offset) {
72 return static_cast<uint8_t *>(address) + (legacy_offset / _elemScriptSize) * _elemMemSize;
73 }
74
75 void *GetFieldPtr(void *address, intptr_t offset) override;
76 void Read(void *address, intptr_t offset, uint8_t *dest, size_t size) override;
77 uint8_t ReadInt8(void *address, intptr_t offset) override;
78 int16_t ReadInt16(void *address, intptr_t offset) override;
79 int32_t ReadInt32(void *address, intptr_t offset) override;
80 float ReadFloat(void *address, intptr_t offset) override;
81 void Write(void *address, intptr_t offset, const uint8_t *src, size_t size) override;
82 void WriteInt8(void *address, intptr_t offset, uint8_t val) override;
83 void WriteInt16(void *address, intptr_t offset, int16_t val) override;
84 void WriteInt32(void *address, intptr_t offset, int32_t val) override;
85 void WriteFloat(void *address, intptr_t offset, float val) override;
86
87private:
88 IScriptObject *_mgr = nullptr;
89 size_t _elemScriptSize = 0u;
90 size_t _elemMemSize = 0u;
91 size_t _elemCount = 0u;
92};
93
94} // namespace AGS3
95
96#endif
Definition: cc_ags_dynamic_object.h:108
Definition: cc_static_array.h:60
Definition: cc_script_object.h:60