summaryrefslogtreecommitdiff
path: root/src/lib/ector/ector_buffer.eo
blob: 1537bd269791d006dddfbe682fd386b67094483f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
import efl_gfx_types;

enum Ector.Buffer.Flag {
   [[Buffer capabilities]]
   none              = 0x00, [[Buffer may not have any backing, indicates an invalid buffer.]]
   cpu_readable      = 0x01, [[Can be read from the CPU after map. Reading may still be very slow.]]
   cpu_writable      = 0x02, [[Can be written to by the CPU after map. Writing may still be very slow.]]
   renderable        = 0x04, [[Can be rendered to, ie CPU memory for SW rendering, or an FBO for GL engine.]]
   drawable          = 0x08, [[Can be used as a source of pixels to draw on Evas.]]
   cpu_readable_fast = 0x10, [[Can be read by the CPU at high speed, ie no need for glReadPixels.]]
   cpu_writable_fast = 0x20, [[Can be written by the CPU at high speed, ie no need for GPU texture upload.]]
   uncached          = 0x40, [[Backed by uncached memory, ie. slow-ish reads but faster than glReadPixels.]]
/* non_coherent      = 0x80, [[Memory may be mapped but will not be coherent between GPU and CPU. Call flush or invalidate to synchronize it.]] */
}

enum Ector.Buffer.Access_Flag {
   [[Buffer access permissions]]
   none      = 0x0, [[No access permission]]
   read      = 0x1, [[Read access permission]]
   write     = 0x2, [[Write access permission]]
   cow       = 0x4, [[Forces copy-on-write if already mapped as read-only. Requires write.]]
}

mixin Ector.Buffer
{
   [[2D pixel buffer interface for Ector
     @since 1.17
   ]]
   eo_prefix: ector_buffer;
   legacy_prefix: null;
   methods {
      @property size {
         [[The (rectangular) size of the pixel buffer.]]
         get {}
         values {
            w: int; [[Width]]
            h: int; [[Height]]
         }
      }
      @property cspace {
         [[The colorspace of the pixel buffer.]]
         get {}
         values {
            cspace: Efl.Gfx.Colorspace; [[Colorspace]]
         }
      }
      map @virtual_pure {
         [[Map a region of this buffer for read or write access by the CPU,
           fetch data from the GPU if needed. This operation may be slow if
           cpu_readable_fast or cpu_writeable_fast are not true, or if the
           required colorspace is different from the internal one.
         ]]
         params {
            @out length: uint; [[Accessible buffer size in bytes, should not be $null.]]
            @in mode: Ector.Buffer.Access_Flag; [[Specifies whether to map for read-only,
                                                  write-only or read-write access (OR combination of flags).]]
            @in x: uint; [[X position of the top-left pixel to map]]
            @in y: uint; [[Y position of the top-left pixel to map]]
            @in w: uint; [[If 0, defaults to the buffer width]]
            @in h: uint; [[If 0, defaults to the buffer height]]
            @in cspace: Efl.Gfx.Colorspace; [[Requested colorspace. If different from the internal cspace,
                                              map should try to convert the data into a new buffer]]
            @out stride: uint @optional; [[Returns the length in bytes of a mapped line]]
         }
         return: void* @warn_unused; [[Pointer to the top-left pixel data. Returns $null in case of failure]]
      }
      unmap @virtual_pure {
         [[Unmap a region of this buffer, and upload data to the GPU (if needed).]]
         params {
            @in data: void*; [[Data pointer returned by a previous call to map]]
            @in length: uint; [[Must be the same as returned by map.]]
         }
      }
      pixels_set @virtual_pure {
         [[Set the source pixels for this buffer, or allocate a new memory region]]
         params {
            @in pixels: void*; [[If $null, allocates an empty buffer]]
            @in width: int; [[Buffer width]]
            @in height: int; [[Buffer height]]
            @in stride: int; [[Can be 0]]
            @in cspace: Efl.Gfx.Colorspace; [[Buffer colorspace]]
            @in writable: bool; [[Buffer is writable]]
            @in l: ubyte; [[Left border pixels, usually 0 or 1]]
            @in r: ubyte; [[Right border pixels, usually 0 or 1]]
            @in t: ubyte; [[Top border pixels, usually 0 or 1]]
            @in b: ubyte; [[Bottom border pixels, usually 0 or 1]]
         }
         return: bool; [[True if pixels_set was successful]]
      }
      span_get @virtual_pure {
         [[Get a single horizontal span of length w starting from (x,y)

           Call span_free() to release it. This function will try not to
           allocate any new buffer, whenever possible. This means the data
           might be mapped directly from the backing memory buffer.
         ]]
         params {
            @in x: int; [[Ranges from -l to w+r-1]]
            @in y: int; [[Ranges from -t to h+b-1]]
            @in w: uint; [[Ranges from 1 to w+l+r]]
            @in cspace: Efl.Gfx.Colorspace; [[Requested colorspace, may trigger conversion on the fly.]]
            @out length: uint; [[Length in bytes of the returned buffer]]
         }
         return: uint8*; [[A temporary memory buffer containing the pixels requested.]]
      }
      span_free @virtual_pure {
         [[Must be called as soon as possible after span_get]]
         params {
            data: uint8*; [[Data to be freed]]
         }
      }
      @property flags {
         [[The capabilities of this buffer]]
         get {}
         values {
            flag: Ector.Buffer.Flag; [[A bitmask of capability flags]]
         }
      }
      @property border {
         [[Duplicated pixel borders of this buffer, used for GL scaling]]
         get {}
         values {
            l: int; [[Left border]]
            r: int; [[Right border]]
            t: int; [[Top border]]
            b: int; [[Bottom border]]
         }
      }
   }
   events {
      detached; [[Emitted whenever the previously attached pixels are detached during pixels_set]]
   }
}