Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions .ai/memory/architecture/activex.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,14 @@ remain in Core.

## Automation contracts

- `IMapWinGISControl`, `IMapWinGISControl2`, `IMapWinGISControl3`, and
`IMapWinGISControl4` are versioned derived interfaces with distinct IIDs.
- `IMapWinGISControl` through `IMapWinGISControl5` are versioned derived
interfaces with distinct IIDs.
Do not add vtable members to a published interface or change its IID.
Extend the contract with a new derived interface when needed.
- The default control interface is `IMapWinGISControl4`. It adds navigation,
layer count, and stable layer-ID access to `IMapWinGISControl3`. The
independent generic GDAL capability uses `IMapWinGISControlGdal`, and
notifications use the separate `IMapWinGISControlEvents` dispinterface.
- The default control interface is `IMapWinGISControl5`. It adds asynchronous
vector loading to `IMapWinGISControl4`; the independent generic GDAL
capability uses `IMapWinGISControlGdal`, and both operations use the
separate `IMapWinGISControlEvents` dispinterface.
- These are new v6 interfaces, not the MapWinGIS 5 type-library contracts.
The current control does not claim v5 binary compatibility.
- Keep COM conversions and COM error translation at this boundary. Core
Expand Down
8 changes: 7 additions & 1 deletion .github/plans/development-review-fix-plan-20261113.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Implement one phase per run and open one PR per phase, in this order. Check a ph
- [x] Phase 6 – Improve COM container compatibility (#6, #20, #24, #27, #37)
- [x] Phase 7 – Rebuild render scenes per layer (#7, #34)
- [x] Phase 8 – Fix ActiveX rendering edge cases (#21, #26, #35, #38)
- [ ] Phase 9 – Load vector datasets asynchronously (#36)
- [x] Phase 9 – Load vector datasets asynchronously (#36)

Finding coverage: every finding is assigned to exactly one phase:

Expand Down Expand Up @@ -401,3 +401,9 @@ Suggested fix:
- GDAL objects created on the worker must not be used concurrently; follow the threading contract documented in Phase 3.

After approval, implement it with tests: load completes and fires the event; cancel leaves the map unchanged; a failed open reports error details; destroying the control during a load is safe.

**Phase 9 result:** Added asynchronous vector loading to `IMapWinGISControl5` at DISPIDs 18-20. The worker prepares the dataset and render scene; the owning apartment commits them before raising the shared `GdalOperationCompleted` event. Cancellation discards the candidate, and the synchronous load methods retain their behavior.

**Validation:** CMake Debug x64 build and all 430 CTest cases passed; three opt-in cases were skipped. MSBuild Debug x64 built with zero warnings. Its Core suite passed 335 tests with one skip, and its ActiveX suite passed 88 tests with three skips. The existing CMake D9025 command-line warning remains.

**Limitations:** Interactive registered-control hosting and network-dependent/opt-in rendering tests were not run locally.
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,10 @@ cancellation events.

The core also supports a shared map viewport with pan, center zoom, anchored
zoom, and fitting to the visible map or a named layer. These navigation calls
do not depend on a window. `IMapWinGISControl4` exposes this programmatic
navigation and stable layer IDs through ActiveX. The control also supports
left-button drag panning and cursor-anchored mouse-wheel zoom. Resizing keeps
the current map center and resolution.
do not depend on a window. `IMapWinGISControl5` exposes this programmatic
navigation, stable layer IDs, and asynchronous vector loading through ActiveX.
The control also supports left-button drag panning and cursor-anchored
mouse-wheel zoom. Resizing keeps the current map center and resolution.

Cached drag frames are reused only for whole-pixel shifts.
Scaled and print draws use temporary rendering buffers and keep the screen
Expand Down
46 changes: 29 additions & 17 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -362,10 +362,11 @@ drawing operation is unsupported. The control reports the active backend and
the reason for a fallback through `RenderingBackend` and `RenderingStatus`.
These rendering properties are on `IMapWinGISControl2`, which derives from
`IMapWinGISControl`. `IMapWinGISControl3` adds `ClearLayers` at DISPID 8.
The coclass default is `IMapWinGISControl4`, which derives from
`IMapWinGISControl3`. It adds map navigation, layer count, and stable layer IDs
at DISPIDs 9-17. The earlier interfaces, their DISPIDs, and their IIDs remain
unchanged.
`IMapWinGISControl4` derives from `IMapWinGISControl3` and adds map navigation,
layer count, and stable layer IDs at DISPIDs 9-17. The coclass default is
`IMapWinGISControl5`, which derives from `IMapWinGISControl4` and adds
asynchronous vector loading at DISPIDs 18-20. The earlier interfaces, their
DISPIDs, and their IIDs remain unchanged.
OpenGL capability detection checks framebuffer-object entry points, the
maximum renderbuffer size, and the maximum viewport dimensions at runtime;
targets exceeding either limit use GDI. CPU staging for OpenGL readback is
Expand Down Expand Up @@ -399,19 +400,23 @@ intentional compatibility gaps and the rationale when interfaces are introduced.

The control exposes a small v6 COM surface: Core initialization, vector
dataset loading, layer-loaded state, feature count, renderer preference,
active backend and status, plus asynchronous generic GDAL operations with
progress, cancellation, and result reporting. The GDAL API has a new interface
and does not claim MapWinGIS 5 `IGdalUtils` binary compatibility.
At most sixteen operations may be active or awaiting result cleanup. Call
`EndGdalOperation` after completion to release an operation slot. The control
delivers events on its owning apartment thread. Destroying the in-place window
suspends notification delivery without cancelling operations; a subsequent
`WM_SIZE` resumes delivery. Calling `Close` or destroying the control after
the client's final COM reference is released cancels outstanding work and
discards queued notifications. An in-progress event dispatch holds a temporary
COM reference, so releasing the client's reference inside an event does not
destroy the control until dispatch returns. Workers never retain COM references
or wait for event handlers.
active backend and status, plus asynchronous vector loading and generic GDAL
operations. The GDAL API has a new interface and does not claim MapWinGIS 5
`IGdalUtils` binary compatibility. Both asynchronous capabilities share one
dispatcher and operation limit: at most sixteen operations may be active or
awaiting result cleanup. `GdalOperationCompleted` signals either kind; call
`EndGdalOperation` or `EndLoadVectorDataset`, respectively, to retrieve the
result and release its slot. Completion is delivered on the owning apartment
thread. For vector loads, the control commits the prepared dataset and scene
before raising the completion event. Cancellation discards the candidate and
leaves the live map unchanged. Destroying the in-place window suspends
notification delivery without cancelling operations; a subsequent `WM_SIZE`
resumes delivery. Calling `Close` or destroying the control after the client's
final COM reference is released cancels outstanding work and discards queued
notifications. An in-progress event dispatch holds a temporary COM reference,
so releasing the client's reference inside an event does not destroy the
control until dispatch returns. Workers never retain COM references or wait for
event handlers.

`LoadVectorDataset` adds the first vector layer of a dataset on top of the
map. Earlier layers stay loaded, so calling it again shows several layers.
Expand All @@ -420,6 +425,13 @@ returns the stable ID of the new layer, and `GetLayerId` returns a layer ID by
its current 0-based position. Call `ClearLayers` before switching or refreshing
datasets to avoid duplicate layers. It releases all loaded datasets and clears
the feature total, but keeps the view.
`IMapWinGISControl5::BeginLoadVectorDataset` performs the same preparation on
the GDAL worker and returns an operation ID. It uses the existing
`GdalOperationCompleted` event; clients retrieve the result and new layer ID
with `EndLoadVectorDataset`. `CancelLoadVectorDataset` does not block. If
cancellation is accepted before the completion event is delivered, the
candidate is discarded and the map is unchanged. The original synchronous
`LoadVectorDataset` and `LoadVectorDatasetEx` methods keep their behavior.
The layer must be polygon-compatible: a dataset whose first layer has another
geometry type fails to load and is not added, even if a later layer is
polygonal. An empty polygon layer loads but draws nothing. The control reads
Expand Down
18 changes: 12 additions & 6 deletions docs/PORTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,12 +72,18 @@ The initial `MapWinGIS.ocx` exposes a deliberately small v6 automation
contract. `IMapWinGISControl` reports Core initialization, loads a vector
dataset, and reports whether a layer is loaded and its feature count.
`IMapWinGISControl2` adds renderer preference, active backend, and status.
`IMapWinGISControl3` adds `ClearLayers`. `IMapWinGISControl4` derives from it
and is the default automation interface; it adds view navigation, layer count,
`LoadVectorDatasetEx`, and stable layer-ID lookup by 0-based position. Loads
add layers, including duplicate loads of one dataset. Each successful load
requests a fit to the combined map extent, replacing any previous pan or zoom
when the extent is valid and the viewport has a size.
`IMapWinGISControl3` adds `ClearLayers`. `IMapWinGISControl4` adds view
navigation, layer count, `LoadVectorDatasetEx`, and stable layer-ID lookup by
0-based position. `IMapWinGISControl5` derives from it and is the default
automation interface; it adds asynchronous vector loading, cancellation, and
result retrieval. It reuses the `GdalOperationCompleted` event and shares the
dispatcher and operation limit with asynchronous GDAL calls. The worker
prepares a candidate dataset and scene; the control commits them on its owning
apartment before the completion event. Cancelling before completion leaves the
map unchanged. The synchronous load methods retain their existing behavior.
Loads add layers, including duplicate loads of one dataset. Each successful
load requests a fit to the combined map extent, replacing any previous pan or
zoom when the extent is valid and the viewport has a size.
Call `ClearLayers` before switching
or refreshing datasets. It releases all layers and resets the cached feature
total while keeping the viewport.
Expand Down
3 changes: 2 additions & 1 deletion docs/TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,8 @@ output folder. CI runs them before the solution build. Builds with
Pull requests run both Debug and full-driver Release tests for x64.

The native `MapWinGIS.ActiveX.Tests` project covers COM activation, rendering
through GDI and OpenGL, and GDAL progress/completion events.
through GDI and OpenGL, GDAL progress/completion events, and asynchronous
vector loads, including cancellation, failure details, and control destruction.
Class-factory tests require no COM registration. They inspect the native
control through test-only friend helpers, without changing its COM interfaces.
They cover whole-pixel cached pan draws, fractional and oversized offsets,
Expand Down
2 changes: 2 additions & 0 deletions docs/gdal-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,8 @@ cancellation, GDAL error code, summary, full diagnostics, callback error code
and message, and warnings, and to release the operation slot. An incomplete
operation returns `E_PENDING`; an unknown or ended identifier returns
`E_INVALIDARG`.
`GdalOperationCompleted` is also reused for asynchronous vector loads exposed
by `IMapWinGISControl5`; retrieve those results with `EndLoadVectorDataset`.
`EndGdalOperation` also returns `E_PENDING` while a progress or completion
event is being delivered. Call it after the event handler returns.

Expand Down
56 changes: 56 additions & 0 deletions src/MapWinGIS.ActiveX/GdalEventSource.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,36 @@ namespace mwg::activex
}
}

std::uint64_t GdalEventSource::BeginWork(
GdalOperationDispatcher::WorkCallback work)
{
if (_closing || _dispatchWindow == nullptr ||
!_dispatchWindow->IsWindow())
{
throw std::runtime_error(
"The GDAL event source is not available for new operations.");
}

_dispatcher.SetWakeCallback(
&GdalEventSource::PostDispatchMessage,
_dispatchWindow.get());
_dispatcher.SetWorkerFinishedCallback(
&GdalEventSource::UnlockActiveXModule,
nullptr);
ArmRetryTimer();
_AtlModule.Lock();
try
{
return _dispatcher.BeginWork(std::move(work), true);
}
catch (...)
{
_AtlModule.Unlock();
UpdateRetryTimer();
throw;
}
}

GdalCancelResult GdalEventSource::Cancel(
const std::uint64_t operationId) noexcept
{
Expand All @@ -135,13 +165,34 @@ namespace mwg::activex
return _dispatcher.GetResult(operationId);
}

GdalOperationLookup GdalEventSource::GetResultForDelivery(
const std::uint64_t operationId) const
{
return _dispatcher.GetResultForDelivery(operationId);
}

void GdalEventSource::UpdateCompletedResult(
const std::uint64_t operationId,
GdalOperationSnapshot result)
{
_dispatcher.UpdateCompletedResult(operationId, std::move(result));
}

GdalOperationLookup GdalEventSource::End(const std::uint64_t operationId)
{
GdalOperationLookup result = _dispatcher.End(operationId);
UpdateRetryTimer();
return result;
}

void GdalEventSource::SetCompletionCallback(
const CompletionCallback callback,
void* const context) noexcept
{
_completionCallback = callback;
_completionContext = context;
}

void GdalEventSource::RecordCallbackError(
const std::uint64_t operationId,
const HRESULT result) noexcept
Expand Down Expand Up @@ -245,6 +296,11 @@ namespace mwg::activex
}
} notificationGuard{_dispatcher, notification.operationId, generation};

if (notification.kind == GdalNotificationKind::Completed &&
_completionCallback != nullptr)
{
_completionCallback(_completionContext, notification.operationId);
}
const HRESULT result =
notification.kind == GdalNotificationKind::Progress
? FireProgress(notification, generation)
Expand Down
14 changes: 14 additions & 0 deletions src/MapWinGIS.ActiveX/GdalEventSource.h
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ namespace mwg::activex
class GdalEventSource final
{
public:
using CompletionCallback = void(*)(void*, std::uint64_t) noexcept;

GdalEventSource(
ATL::CComDynamicUnkArray& sinks,
GdalDispatchWindow::Callback callback,
Expand All @@ -40,10 +42,20 @@ namespace mwg::activex
[[nodiscard]] std::uint64_t Begin(
std::string algorithmPath,
std::vector<std::string> arguments);
[[nodiscard]] std::uint64_t BeginWork(
GdalOperationDispatcher::WorkCallback work);
[[nodiscard]] GdalCancelResult Cancel(std::uint64_t operationId) noexcept;
[[nodiscard]] GdalOperationLookup GetResult(
std::uint64_t operationId) const;
[[nodiscard]] GdalOperationLookup GetResultForDelivery(
std::uint64_t operationId) const;
void UpdateCompletedResult(
std::uint64_t operationId,
GdalOperationSnapshot result);
[[nodiscard]] GdalOperationLookup End(std::uint64_t operationId);
void SetCompletionCallback(
CompletionCallback callback,
void* context) noexcept;
void RecordCallbackError(
std::uint64_t operationId,
HRESULT result) noexcept;
Expand Down Expand Up @@ -76,6 +88,8 @@ namespace mwg::activex
ATL::CComDynamicUnkArray& _sinks;
GdalDispatchWindow::Callback _dispatchCallback = nullptr;
void* _dispatchContext = nullptr;
CompletionCallback _completionCallback = nullptr;
void* _completionContext = nullptr;
std::shared_ptr<GdalDispatchWindow> _dispatchWindow;
bool _dispatching = false;
bool _dispatchWindowDestroyPending = false;
Expand Down
Loading