AllocDBufInfo

Allocate structure for multi-buffered animation

Declaration

Source position: agraphics.pas line 2459

Arguments

Function result

Returns 0 if there is no memory available or if the display mode of the viewport does not support double-buffering.

Description

Allocates a structure which is used by the ChangeVPBitMap() routine.

The only fields of the TDBufInfo structure which can be used by application programs are the dbi_SafeMessage, dbi_DispMessage, dbi_UserData1 and dbi_UserData2 fields.

dbi_SafeMessage and dbi_DispMessage are standard exec message structures which may be used for synchronizing your animation with the screen update.

dbi_SafeMessage is a message which is replied to when it is safe to write to the old BitMap (the one which was installed when you called ChangeVPBitMap()).

dbi_DispMessage is replied to when it is safe to call ChangeVPBitMap() again and be certain that the new frame has been seen at least once.

The dbi_UserData1 and dbi_UserData2 fields, which are stored after each message, are for your application to stuff any data into that it may need to examine when looking at the reply coming into the ReplyPort for either of the embedded Message structures.

TDBufInfo structures must be allocated with this function. The size of the structure will grow in future releases.

See also

Example

// The following fragment shows proper double buffering synchronization:
var
  SafeToChange: Boolean = True;
  SafeToWrite: Boolean = True;
  CurBuffer: Integer = 1;
  Ports: array[0..1] of PMsgPort; // reply ports for DispMessage and SafeMessage
  BmPtrs: array[0..1] of PBitmap;
  myDBI: PDBufInfo;
begin
  //... allocate bitmap pointers, DBufInfo, set up viewports, create Ports etc.
  myDBI^.dbi_SafeMessage.mn_ReplyPort := ports[0];
  myDBI^.dbi_DispMessage.mn_ReplyPort := ports[1];
  while not done do
  begin
    if not SafeToWrite then
    begin
      while GetMsg(ports[0]) = nil do
        Wait(1 shl ports[0]^.mp_SigBit);
    end;
    SafeToWrite := True;
// ... render to bitmap # CurBuffer.
    if not SafeToChange then
    begin
      while GetMsg(ports[1]) = nil do
        Wait(1 shl ports[1]^.mp_SigBit);
    end;
    SafeToChange := True;
    WaitBlit();         // be sure rendering has finished
    ChangeVPBitMap(vp, BmPtrs[CurBuffer], myDBI);
    SafeToChange := False;
    SafeToWrite := False;
    CurBuffer := (CurBuffer + 1) and 1; // toggle current buffer
  end;
  if not SafeToChange then
  begin
    while GetMsg(ports[1]) = nil do
      Wait(1 shl ports[1]^.mp_SigBit);
  end;
  if not SafeToWrite then
  begin
    while GetMsg(ports[0]) = nil do
      Wait(1 shl ports[0]^.mp_SigBit);
  end;
end;