4.51.2.4. ogSurface object	Table of Contents	4.51.2.4.2. ogArc()

  function ogAlias(var srcObject:ogSurface; x1, y1, x2, y2:uInt32):boolean; virtual;

ogSurface objects are able to "alias" rectangular sections of other ogSurface objects. For example, if you allocate a 640x480 surface with one ogSurface object you may "alias" a 320x200 rectangular region of that surface with another ogSurface object.

An "aliased" object is generally referred to as the parent or owner provided that it was the surface which called ogCreate(), and an "aliasing" object is generally referred to as the child. The owner buffer contains the allocated memory for the graphics buffer, palette, and line offset array (among others). The child surface uses pointers to these items.

Because all drawing methods clip, aliasing another object is a clever way to emulate viewports. However, unlike viewports, you may treat each object separately even though their buffers share part of the same memory space. This means, for example, that you may load/save graphics files into aliased sections.

You may also alias aliasing objects.

Aliasing objects are not limited to a smaller buffer size than the original. It is valid to do:

A_Buf and OwnerBuf now share the same memory. All drawing to A_Buf will occur in OwnerBuf and vice versa.

TRUE if successful, FALSE if there was an error.

You do not have to destruct aliasing/aliased surfaces in any particular order, but once the owner surface has been destructed (through a call to ogDone()) you may no longer draw to the aliasing surface. Aliasing surfaces contain no allocated memory of their own, so they do not necessarily need to be destructed (although it is a good idea to do so). In the event that the owner surface calls ogCreate() again, the aliasing surface will be invalid. Child surfaces are not aware of pixel format/BPP or resolution changes of their parent. This might be fixed in a future revision.

You cannot alias a region that goes outside the coordinate pair (0,0),(ogGetMaxX,ogGetMaxY) of the surface that you are attempting to alias.

The screen may not alias other surfaces. Screen^.ogAlias() will always return FALSE.

Surfaces may not alias themselves.

Objects that have allocated memory via ogCreate() may not alias other surfaces.

See Also:

• ogDisplay.ogAlias()
• ogSurface.ogGetDataState()
• ogDataState type
• OG_DATA_STATE_STR[]

{ogAlias.pas}

uses
 ObjGfx40, CRT;

var 
  ownerObj, aliasedObj:^ogSurface;
  
begin
  {Init all the objects}
  new(ownerObj, ogInit);
  new(aliasedObj, ogInit);

  {Allocate a 640x480x256c surface in ownerObj}
  if not ownerObj^.ogCreate(640, 480, OG_PIXFMT_8BPP) then
    begin
      writeln('Error allocating memory for double-buffer');
      halt
    end;

  {Alias a section of OwnerObj}
  {Note that the aliased object doesn't need to call ogCreate() since
   it will be aliasing memory in the OwnerObj}
  aliasedObj^.ogAlias(OwnerObj^, 50, 50, 125, 125);

  {the screen object is inside ObjGfx40. Construction/destruction
   occurs inside the unit}
  if not screen^.ogCreate(640, 480, OG_PIXFMT_8BPP) then
    begin
      writeln('Error setting video mode');
      halt
    end;

  {Clear all of the ownerObj to white}
  ownerObj^.ogClear(ownerObj^.ogRGB(255, 255, 255));

  {Clear all of the AliasedObj to gray.. note what this does}
  aliasedObj^.ogClear(aliasedObj^.ogRGB(128, 128, 128));

  {Copy all of OwnerObj to the screen}
  screen^.ogCopy(OwnerObj^);

  readkey;  {wait for a key}

  {You may dispose of aliased objects last so long as you don't try
   to use an aliased object after the parent has been destructed.}
  dispose(aliasedObj, ogDone);
  dispose(ownerObj, ogDone);
end.

4.51.2.4. ogSurface object	Table of Contents	4.51.2.4.2. ogArc()